0
# Options Factory
1

2
Factory pattern for customizing RocksDB database and column family options, enabling fine-grained performance tuning for specific use cases and hardware configurations.
3

4
## Capabilities
5

6
### RocksDBOptionsFactory Interface
7

8
The core interface for creating custom RocksDB options.
9

10
```java { .api }
11
/**
12
 * Factory interface for creating RocksDB options.
13
 * Allows customization of database options, column family options, and other RocksDB settings.
14
 */
15
interface RocksDBOptionsFactory extends Serializable {
16
    
17
    /**
18
     * Creates or modifies database options for RocksDB.
19
     * @param currentOptions current DB options to modify
20
     * @param handlesToClose collection to register objects that need cleanup
21
     * @return configured DB options
22
     */
23
    DBOptions createDBOptions(DBOptions currentOptions, Collection<AutoCloseable> handlesToClose);
24
    
25
    /**
26
     * Creates or modifies column family options for RocksDB.
27
     * @param currentOptions current column family options to modify  
28
     * @param handlesToClose collection to register objects that need cleanup
29
     * @return configured column family options
30
     */
31
    ColumnFamilyOptions createColumnOptions(ColumnFamilyOptions currentOptions, Collection<AutoCloseable> handlesToClose);
32
    
33
    /**
34
     * Creates native metrics options for RocksDB monitoring.
35
     * @param nativeMetricOptions current native metrics options
36
     * @return configured native metrics options
37
     */
38
    default RocksDBNativeMetricOptions createNativeMetricsOptions(RocksDBNativeMetricOptions nativeMetricOptions) {
39
        return nativeMetricOptions;
40
    }
41
    
42
    /**
43
     * Creates write options for RocksDB write operations.
44
     * @param currentOptions current write options to modify
45
     * @param handlesToClose collection to register objects that need cleanup
46
     * @return configured write options
47
     */
48
    default WriteOptions createWriteOptions(WriteOptions currentOptions, Collection<AutoCloseable> handlesToClose) {
49
        return currentOptions;
50
    }
51
    
52
    /**
53
     * Creates read options for RocksDB read operations.
54
     * @param currentOptions current read options to modify
55
     * @param handlesToClose collection to register objects that need cleanup
56
     * @return configured read options
57
     */
58
    default ReadOptions createReadOptions(ReadOptions currentOptions, Collection<AutoCloseable> handlesToClose) {
59
        return currentOptions;
60
    }
61
}
62
```
63

64
**Usage Example:**
65

66
```java
67
// Custom options factory implementation
68
RocksDBOptionsFactory customFactory = new RocksDBOptionsFactory() {
69
    @Override
70
    public DBOptions createDBOptions(DBOptions currentOptions, Collection<AutoCloseable> handlesToClose) {
71
        return currentOptions
72
            .setMaxOpenFiles(1024)
73
            .setMaxBackgroundJobs(4)
74
            .setUseFsync(false);
75
    }
76
    
77
    @Override
78
    public ColumnFamilyOptions createColumnOptions(ColumnFamilyOptions currentOptions, Collection<AutoCloseable> handlesToClose) {
79
        BloomFilter bloomFilter = new BloomFilter(10);
80
        handlesToClose.add(bloomFilter);
81
        
82
        return currentOptions
83
            .setWriteBufferSize(128 * 1024 * 1024)  // 128MB
84
            .setTableFormatConfig(
85
                new BlockBasedTableConfig().setFilter(bloomFilter)
86
            );
87
    }
88
};
89

90
stateBackend.setRocksDBOptions(customFactory);
91
```
92

93
### DefaultConfigurableOptionsFactory
94

95
Default implementation that provides configurable options through method chaining.
96

97
```java { .api }
98
/**
99
 * Default configurable options factory that can be configured through method chaining.
100
 * Provides common RocksDB configuration options with sensible defaults.
101
 */
102
class DefaultConfigurableOptionsFactory implements RocksDBOptionsFactory, ConfigurableRocksDBOptionsFactory {
103
    
104
    /**
105
     * Creates a new factory instance.
106
     */
107
    DefaultConfigurableOptionsFactory();
108
    
109
    /**
110
     * Creates a configured factory from ReadableConfig.
111
     * @param configuration configuration to read from
112
     * @return configured factory instance
113
     */
114
    DefaultConfigurableOptionsFactory configure(ReadableConfig configuration);
115
}
116
```
117

118
### Database Options Configuration
119

120
Configure RocksDB database-level options.
121

122
```java { .api }
123
/**
124
 * Sets the total number of background threads (compaction + flush).
125
 * @param totalThreadCount total background thread count
126
 * @return this factory for method chaining
127
 */
128
DefaultConfigurableOptionsFactory setMaxBackgroundThreads(int totalThreadCount);
129

130
/**
131
 * Sets the maximum number of open files that RocksDB can keep open.
132
 * @param maxOpenFiles maximum open files (-1 for unlimited)
133
 * @return this factory for method chaining
134
 */
135
DefaultConfigurableOptionsFactory setMaxOpenFiles(int maxOpenFiles);
136

137
/**
138
 * Sets the log level for RocksDB logging.
139
 * @param logLevel log level for RocksDB
140
 * @return this factory for method chaining
141
 */
142
DefaultConfigurableOptionsFactory setLogLevel(InfoLogLevel logLevel);
143

144
/**
145
 * Sets the directory for RocksDB log files.
146
 * @param logDir directory path for log files
147
 * @return this factory for method chaining
148
 */
149
DefaultConfigurableOptionsFactory setLogDir(String logDir);
150

151
/**
152
 * Sets the maximum size of a single log file.
153
 * @param maxLogFileSize maximum log file size (e.g., "64mb")
154
 * @return this factory for method chaining
155
 */
156
DefaultConfigurableOptionsFactory setMaxLogFileSize(String maxLogFileSize);
157

158
/**
159
 * Sets the number of log files to keep.
160
 * @param logFileNum number of log files to retain
161
 * @return this factory for method chaining
162
 */
163
DefaultConfigurableOptionsFactory setLogFileNum(int logFileNum);
164
```
165

166
### Column Family Options Configuration
167

168
Configure RocksDB column family options for performance tuning.
169

170
```java { .api }
171
/**
172
 * Sets the compaction style for RocksDB.
173
 * @param compactionStyle compaction algorithm to use
174
 * @return this factory for method chaining
175
 */
176
DefaultConfigurableOptionsFactory setCompactionStyle(CompactionStyle compactionStyle);
177

178
/**
179
 * Enables or disables dynamic level size adjustment.
180
 * @param value whether to use dynamic level sizes
181
 * @return this factory for method chaining
182
 */
183
DefaultConfigurableOptionsFactory setUseDynamicLevelSize(boolean value);
184

185
/**
186
 * Sets the target file size for L1 level.
187
 * @param targetFileSizeBase target file size (e.g., "64mb")
188
 * @return this factory for method chaining
189
 */
190
DefaultConfigurableOptionsFactory setTargetFileSizeBase(String targetFileSizeBase);
191

192
/**
193
 * Sets the maximum total data size for level L1.
194
 * @param maxSizeLevelBase maximum size for L1 (e.g., "256mb")
195
 * @return this factory for method chaining
196
 */
197
DefaultConfigurableOptionsFactory setMaxSizeLevelBase(String maxSizeLevelBase);
198

199
/**
200
 * Sets the size of write buffer (memtable).
201
 * @param writeBufferSize write buffer size (e.g., "64mb")
202
 * @return this factory for method chaining
203
 */
204
DefaultConfigurableOptionsFactory setWriteBufferSize(String writeBufferSize);
205

206
/**
207
 * Sets the maximum number of write buffers.
208
 * @param writeBufferNumber maximum write buffer count
209
 * @return this factory for method chaining
210
 */
211
DefaultConfigurableOptionsFactory setMaxWriteBufferNumber(int writeBufferNumber);
212

213
/**
214
 * Sets the minimum number of write buffers to merge.
215
 * @param writeBufferNumber minimum buffers to merge
216
 * @return this factory for method chaining
217
 */
218
DefaultConfigurableOptionsFactory setMinWriteBufferNumberToMerge(int writeBufferNumber);
219
```
220

221
### Block and Cache Configuration
222

223
Configure block size and caching options.
224

225
```java { .api }
226
/**
227
 * Sets the block size for RocksDB.
228
 * @param blockSize block size (e.g., "4kb", "16kb")
229
 * @return this factory for method chaining
230
 */
231
DefaultConfigurableOptionsFactory setBlockSize(String blockSize);
232

233
/**
234
 * Sets the metadata block size.
235
 * @param metadataBlockSize metadata block size (e.g., "4kb")
236
 * @return this factory for method chaining
237
 */
238
DefaultConfigurableOptionsFactory setMetadataBlockSize(String metadataBlockSize);
239

240
/**
241
 * Sets the block cache size for frequently accessed blocks.
242
 * @param blockCacheSize block cache size (e.g., "256mb")
243
 * @return this factory for method chaining
244
 */
245
DefaultConfigurableOptionsFactory setBlockCacheSize(String blockCacheSize);
246
```
247

248
### Bloom Filter Configuration
249

250
Configure Bloom filter options for read performance optimization.
251

252
```java { .api }
253
/**
254
 * Enables or disables Bloom filter.
255
 * @param useBloomFilter whether to use Bloom filter
256
 * @return this factory for method chaining
257
 */
258
DefaultConfigurableOptionsFactory setUseBloomFilter(boolean useBloomFilter);
259

260
/**
261
 * Sets the number of bits per key for Bloom filter.
262
 * @param bitsPerKey bits per key for Bloom filter (typically 10)
263
 * @return this factory for method chaining
264
 */
265
DefaultConfigurableOptionsFactory setBloomFilterBitsPerKey(double bitsPerKey);
266

267
/**
268
 * Sets the Bloom filter mode (block-based vs full filter).
269
 * @param blockBasedMode true for block-based, false for full filter
270
 * @return this factory for method chaining
271
 */
272
DefaultConfigurableOptionsFactory setBloomFilterBlockBasedMode(boolean blockBasedMode);
273
```
274

275
**Usage Examples:**
276

277
```java
278
// Basic configuration
279
DefaultConfigurableOptionsFactory factory = new DefaultConfigurableOptionsFactory()
280
    .setMaxBackgroundThreads(4)
281
    .setMaxOpenFiles(-1)
282
    .setWriteBufferSize("128mb")
283
    .setBlockCacheSize("256mb");
284

285
// Advanced configuration with Bloom filter
286
DefaultConfigurableOptionsFactory advancedFactory = new DefaultConfigurableOptionsFactory()
287
    .setCompactionStyle(CompactionStyle.LEVEL)
288
    .setUseDynamicLevelSize(true)
289
    .setTargetFileSizeBase("64mb")
290
    .setMaxSizeLevelBase("256mb")
291
    .setWriteBufferSize("64mb")
292
    .setMaxWriteBufferNumber(3)
293
    .setMinWriteBufferNumberToMerge(2)
294
    .setBlockSize("16kb")
295
    .setBlockCacheSize("512mb")
296
    .setUseBloomFilter(true)
297
    .setBloomFilterBitsPerKey(10.0)
298
    .setBloomFilterBlockBasedMode(false);
299

300
stateBackend.setRocksDBOptions(advancedFactory);
301
```
302

303
### ConfigurableRocksDBOptionsFactory Interface
304

305
Interface for factories that can be configured from Flink configuration.
306

307
```java { .api }
308
/**
309
 * Interface for RocksDB options factories that can be configured from ReadableConfig.
310
 */
311
interface ConfigurableRocksDBOptionsFactory {
312
    
313
    /**
314
     * Creates a configured factory from ReadableConfig.
315
     * @param configuration configuration to read settings from
316
     * @return configured RocksDBOptionsFactory instance
317
     */
318
    RocksDBOptionsFactory configure(ReadableConfig configuration);
319
}
320
```
321

322
## Types
323

324
```java { .api }
325
// RocksDB native types (from org.rocksdb package)
326
enum CompactionStyle {
327
    LEVEL,      // Level-based compaction (default)
328
    UNIVERSAL,  // Universal compaction
329
    FIFO,       // FIFO compaction
330
    NONE        // No compaction
331
}
332

333
enum InfoLogLevel {
334
    DEBUG_LEVEL,
335
    INFO_LEVEL,
336
    WARN_LEVEL,
337
    ERROR_LEVEL,
338
    FATAL_LEVEL,
339
    HEADER_LEVEL
340
}
341

342
class DBOptions {
343
    // RocksDB database options
344
}
345

346
class ColumnFamilyOptions {
347
    // RocksDB column family options
348
}
349

350
class WriteOptions {
351
    // RocksDB write options
352
}
353

354
class ReadOptions {
355
    // RocksDB read options
356
}
357
```