ceph/src/rocksdb/java/src/main/java/org/rocksdb/ColumnFamilyOptionsInterface.java

   1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
   2 //  This source code is licensed under both the GPLv2 (found in the
   3 //  COPYING file in the root directory) and Apache 2.0 License
   4 //  (found in the LICENSE.Apache file in the root directory).
   5
   6 package org.rocksdb;
   7
   8 public interface ColumnFamilyOptionsInterface
   9     <T extends ColumnFamilyOptionsInterface>
  10         extends AdvancedColumnFamilyOptionsInterface<T> {
  11
  12   /**
  13    * Use this if your DB is very small (like under 1GB) and you don't want to
  14    * spend lots of memory for memtables.
  15    *
  16    * @return the instance of the current object.
  17    */
  18   T optimizeForSmallDb();
  19
  20   /**
  21    * Use this if you don't need to keep the data sorted, i.e. you'll never use
  22    * an iterator, only Put() and Get() API calls
  23    *
  24    * @param blockCacheSizeMb Block cache size in MB
  25    * @return the instance of the current object.
  26    */
  27   T optimizeForPointLookup(long blockCacheSizeMb);
  28
  29   /**
  30    * <p>Default values for some parameters in ColumnFamilyOptions are not
  31    * optimized for heavy workloads and big datasets, which means you might
  32    * observe write stalls under some conditions. As a starting point for tuning
  33    * RocksDB options, use the following for level style compaction.</p>
  34    *
  35    * <p>Make sure to also call IncreaseParallelism(), which will provide the
  36    * biggest performance gains.</p>
  37    * <p>Note: we might use more memory than memtable_memory_budget during high
  38    * write rate period</p>
  39    *
  40    * @return the instance of the current object.
  41    */
  42   T optimizeLevelStyleCompaction();
  43
  44   /**
  45    * <p>Default values for some parameters in ColumnFamilyOptions are not
  46    * optimized for heavy workloads and big datasets, which means you might
  47    * observe write stalls under some conditions. As a starting point for tuning
  48    * RocksDB options, use the following for level style compaction.</p>
  49    *
  50    * <p>Make sure to also call IncreaseParallelism(), which will provide the
  51    * biggest performance gains.</p>
  52    * <p>Note: we might use more memory than memtable_memory_budget during high
  53    * write rate period</p>
  54    *
  55    * @param memtableMemoryBudget memory budget in bytes
  56    * @return the instance of the current object.
  57    */
  58   T optimizeLevelStyleCompaction(
  59       long memtableMemoryBudget);
  60
  61   /**
  62    * <p>Default values for some parameters in ColumnFamilyOptions are not
  63    * optimized for heavy workloads and big datasets, which means you might
  64    * observe write stalls under some conditions. As a starting point for tuning
  65    * RocksDB options, use the following for universal style compaction.</p>
  66    *
  67    * <p>Universal style compaction is focused on reducing Write Amplification
  68    * Factor for big data sets, but increases Space Amplification.</p>
  69    *
  70    * <p>Make sure to also call IncreaseParallelism(), which will provide the
  71    * biggest performance gains.</p>
  72    *
  73    * <p>Note: we might use more memory than memtable_memory_budget during high
  74    * write rate period</p>
  75    *
  76    * @return the instance of the current object.
  77    */
  78   T optimizeUniversalStyleCompaction();
  79
  80   /**
  81    * <p>Default values for some parameters in ColumnFamilyOptions are not
  82    * optimized for heavy workloads and big datasets, which means you might
  83    * observe write stalls under some conditions. As a starting point for tuning
  84    * RocksDB options, use the following for universal style compaction.</p>
  85    *
  86    * <p>Universal style compaction is focused on reducing Write Amplification
  87    * Factor for big data sets, but increases Space Amplification.</p>
  88    *
  89    * <p>Make sure to also call IncreaseParallelism(), which will provide the
  90    * biggest performance gains.</p>
  91    *
  92    * <p>Note: we might use more memory than memtable_memory_budget during high
  93    * write rate period</p>
  94    *
  95    * @param memtableMemoryBudget memory budget in bytes
  96    * @return the instance of the current object.
  97    */
  98   T optimizeUniversalStyleCompaction(
  99       long memtableMemoryBudget);
 100
 101   /**
 102    * Set {@link BuiltinComparator} to be used with RocksDB.
 103    *
 104    * Note: Comparator can be set once upon database creation.
 105    *
 106    * Default: BytewiseComparator.
 107    * @param builtinComparator a {@link BuiltinComparator} type.
 108    * @return the instance of the current object.
 109    */
 110   T setComparator(
 111       BuiltinComparator builtinComparator);
 112
 113   /**
 114    * Use the specified comparator for key ordering.
 115    *
 116    * Comparator should not be disposed before options instances using this comparator is
 117    * disposed. If dispose() function is not called, then comparator object will be
 118    * GC'd automatically.
 119    *
 120    * Comparator instance can be re-used in multiple options instances.
 121    *
 122    * @param comparator java instance.
 123    * @return the instance of the current object.
 124    */
 125   T setComparator(
 126       AbstractComparator<? extends AbstractSlice<?>> comparator);
 127
 128   /**
 129    * <p>Set the merge operator to be used for merging two merge operands
 130    * of the same key. The merge function is invoked during
 131    * compaction and at lookup time, if multiple key/value pairs belonging
 132    * to the same key are found in the database.</p>
 133    *
 134    * @param name the name of the merge function, as defined by
 135    * the MergeOperators factory (see utilities/MergeOperators.h)
 136    * The merge function is specified by name and must be one of the
 137    * standard merge operators provided by RocksDB. The available
 138    * operators are "put", "uint64add", "stringappend" and "stringappendtest".
 139    * @return the instance of the current object.
 140    */
 141   T setMergeOperatorName(String name);
 142
 143   /**
 144    * <p>Set the merge operator to be used for merging two different key/value
 145    * pairs that share the same key. The merge function is invoked during
 146    * compaction and at lookup time, if multiple key/value pairs belonging
 147    * to the same key are found in the database.</p>
 148    *
 149    * @param mergeOperator {@link MergeOperator} instance.
 150    * @return the instance of the current object.
 151    */
 152   T setMergeOperator(MergeOperator mergeOperator);
 153
 154   /**
 155    * A single CompactionFilter instance to call into during compaction.
 156    * Allows an application to modify/delete a key-value during background
 157    * compaction.
 158    *
 159    * If the client requires a new compaction filter to be used for different
 160    * compaction runs, it can specify call
 161    * {@link #setCompactionFilterFactory(AbstractCompactionFilterFactory)}
 162    * instead.
 163    *
 164    * The client should specify only set one of the two.
 165    * {@link #setCompactionFilter(AbstractCompactionFilter)} takes precedence
 166    * over {@link #setCompactionFilterFactory(AbstractCompactionFilterFactory)}
 167    * if the client specifies both.
 168    *
 169    * If multithreaded compaction is being used, the supplied CompactionFilter
 170    * instance may be used from different threads concurrently and so should be thread-safe.
 171    *
 172    * @param compactionFilter {@link AbstractCompactionFilter} instance.
 173    * @return the instance of the current object.
 174    */
 175   T setCompactionFilter(
 176           final AbstractCompactionFilter<? extends AbstractSlice<?>> compactionFilter);
 177
 178   /**
 179    * Accessor for the CompactionFilter instance in use.
 180    *
 181    * @return  Reference to the CompactionFilter, or null if one hasn't been set.
 182    */
 183   AbstractCompactionFilter<? extends AbstractSlice<?>> compactionFilter();
 184
 185   /**
 186    * This is a factory that provides {@link AbstractCompactionFilter} objects
 187    * which allow an application to modify/delete a key-value during background
 188    * compaction.
 189    *
 190    * A new filter will be created on each compaction run.  If multithreaded
 191    * compaction is being used, each created CompactionFilter will only be used
 192    * from a single thread and so does not need to be thread-safe.
 193    *
 194    * @param compactionFilterFactory {@link AbstractCompactionFilterFactory} instance.
 195    * @return the instance of the current object.
 196    */
 197   T setCompactionFilterFactory(
 198           final AbstractCompactionFilterFactory<? extends AbstractCompactionFilter<?>>
 199                   compactionFilterFactory);
 200
 201   /**
 202    * Accessor for the CompactionFilterFactory instance in use.
 203    *
 204    * @return  Reference to the CompactionFilterFactory, or null if one hasn't been set.
 205    */
 206   AbstractCompactionFilterFactory<? extends AbstractCompactionFilter<?>> compactionFilterFactory();
 207
 208   /**
 209    * This prefix-extractor uses the first n bytes of a key as its prefix.
 210    *
 211    * In some hash-based memtable representation such as HashLinkedList
 212    * and HashSkipList, prefixes are used to partition the keys into
 213    * several buckets.  Prefix extractor is used to specify how to
 214    * extract the prefix given a key.
 215    *
 216    * @param n use the first n bytes of a key as its prefix.
 217    * @return the reference to the current option.
 218    */
 219   T useFixedLengthPrefixExtractor(int n);
 220
 221   /**
 222    * Same as fixed length prefix extractor, except that when slice is
 223    * shorter than the fixed length, it will use the full key.
 224    *
 225    * @param n use the first n bytes of a key as its prefix.
 226    * @return the reference to the current option.
 227    */
 228   T useCappedPrefixExtractor(int n);
 229
 230   /**
 231    * Number of files to trigger level-0 compaction. A value &lt; 0 means that
 232    * level-0 compaction will not be triggered by number of files at all.
 233    * Default: 4
 234    *
 235    * @param numFiles the number of files in level-0 to trigger compaction.
 236    * @return the reference to the current option.
 237    */
 238   T setLevelZeroFileNumCompactionTrigger(
 239       int numFiles);
 240
 241   /**
 242    * The number of files in level 0 to trigger compaction from level-0 to
 243    * level-1.  A value &lt; 0 means that level-0 compaction will not be
 244    * triggered by number of files at all.
 245    * Default: 4
 246    *
 247    * @return the number of files in level 0 to trigger compaction.
 248    */
 249   int levelZeroFileNumCompactionTrigger();
 250
 251   /**
 252    * Soft limit on number of level-0 files. We start slowing down writes at this
 253    * point. A value &lt; 0 means that no writing slow down will be triggered by
 254    * number of files in level-0.
 255    *
 256    * @param numFiles soft limit on number of level-0 files.
 257    * @return the reference to the current option.
 258    */
 259   T setLevelZeroSlowdownWritesTrigger(
 260       int numFiles);
 261
 262   /**
 263    * Soft limit on the number of level-0 files. We start slowing down writes
 264    * at this point. A value &lt; 0 means that no writing slow down will be
 265    * triggered by number of files in level-0.
 266    *
 267    * @return the soft limit on the number of level-0 files.
 268    */
 269   int levelZeroSlowdownWritesTrigger();
 270
 271   /**
 272    * Maximum number of level-0 files.  We stop writes at this point.
 273    *
 274    * @param numFiles the hard limit of the number of level-0 files.
 275    * @return the reference to the current option.
 276    */
 277   T setLevelZeroStopWritesTrigger(int numFiles);
 278
 279   /**
 280    * Maximum number of level-0 files.  We stop writes at this point.
 281    *
 282    * @return the hard limit of the number of level-0 file.
 283    */
 284   int levelZeroStopWritesTrigger();
 285
 286   /**
 287    * The ratio between the total size of level-(L+1) files and the total
 288    * size of level-L files for all L.
 289    * DEFAULT: 10
 290    *
 291    * @param multiplier the ratio between the total size of level-(L+1)
 292    *     files and the total size of level-L files for all L.
 293    * @return the reference to the current option.
 294    */
 295   T setMaxBytesForLevelMultiplier(
 296       double multiplier);
 297
 298   /**
 299    * The ratio between the total size of level-(L+1) files and the total
 300    * size of level-L files for all L.
 301    * DEFAULT: 10
 302    *
 303    * @return the ratio between the total size of level-(L+1) files and
 304    *     the total size of level-L files for all L.
 305    */
 306   double maxBytesForLevelMultiplier();
 307
 308   /**
 309    * FIFO compaction option.
 310    * The oldest table file will be deleted
 311    * once the sum of table files reaches this size.
 312    * The default value is 1GB (1 * 1024 * 1024 * 1024).
 313    *
 314    * @param maxTableFilesSize the size limit of the total sum of table files.
 315    * @return the instance of the current object.
 316    */
 317   T setMaxTableFilesSizeFIFO(
 318       long maxTableFilesSize);
 319
 320   /**
 321    * FIFO compaction option.
 322    * The oldest table file will be deleted
 323    * once the sum of table files reaches this size.
 324    * The default value is 1GB (1 * 1024 * 1024 * 1024).
 325    *
 326    * @return the size limit of the total sum of table files.
 327    */
 328   long maxTableFilesSizeFIFO();
 329
 330   /**
 331    * Get the config for mem-table.
 332    *
 333    * @return the mem-table config.
 334    */
 335   MemTableConfig memTableConfig();
 336
 337   /**
 338    * Set the config for mem-table.
 339    *
 340    * @param memTableConfig the mem-table config.
 341    * @return the instance of the current object.
 342    * @throws java.lang.IllegalArgumentException thrown on 32-Bit platforms
 343    *   while overflowing the underlying platform specific value.
 344    */
 345   T setMemTableConfig(MemTableConfig memTableConfig);
 346
 347   /**
 348    * Returns the name of the current mem table representation.
 349    * Memtable format can be set using setTableFormatConfig.
 350    *
 351    * @return the name of the currently-used memtable factory.
 352    * @see #setTableFormatConfig(org.rocksdb.TableFormatConfig)
 353    */
 354   String memTableFactoryName();
 355
 356   /**
 357    * Get the config for table format.
 358    *
 359    * @return the table format config.
 360    */
 361   TableFormatConfig tableFormatConfig();
 362
 363   /**
 364    * Set the config for table format.
 365    *
 366    * @param config the table format config.
 367    * @return the reference of the current options.
 368    */
 369   T setTableFormatConfig(TableFormatConfig config);
 370
 371   /**
 372    * @return the name of the currently used table factory.
 373    */
 374   String tableFactoryName();
 375
 376   /**
 377    * Compression algorithm that will be used for the bottommost level that
 378    * contain files. If level-compaction is used, this option will only affect
 379    * levels after base level.
 380    *
 381    * Default: {@link CompressionType#DISABLE_COMPRESSION_OPTION}
 382    *
 383    * @param bottommostCompressionType  The compression type to use for the
 384    *     bottommost level
 385    *
 386    * @return the reference of the current options.
 387    */
 388   T setBottommostCompressionType(
 389       final CompressionType bottommostCompressionType);
 390
 391   /**
 392    * Compression algorithm that will be used for the bottommost level that
 393    * contain files. If level-compaction is used, this option will only affect
 394    * levels after base level.
 395    *
 396    * Default: {@link CompressionType#DISABLE_COMPRESSION_OPTION}
 397    *
 398    * @return The compression type used for the bottommost level
 399    */
 400   CompressionType bottommostCompressionType();
 401
 402   /**
 403    * Set the options for compression algorithms used by
 404    * {@link #bottommostCompressionType()} if it is enabled.
 405    *
 406    * To enable it, please see the definition of
 407    * {@link CompressionOptions}.
 408    *
 409    * @param compressionOptions the bottom most compression options.
 410    *
 411    * @return the reference of the current options.
 412    */
 413   T setBottommostCompressionOptions(
 414       final CompressionOptions compressionOptions);
 415
 416   /**
 417    * Get the bottom most compression options.
 418    *
 419    * See {@link #setBottommostCompressionOptions(CompressionOptions)}.
 420    *
 421    * @return the bottom most compression options.
 422    */
 423   CompressionOptions bottommostCompressionOptions();
 424
 425   /**
 426    * Set the different options for compression algorithms
 427    *
 428    * @param compressionOptions The compression options
 429    *
 430    * @return the reference of the current options.
 431    */
 432   T setCompressionOptions(
 433       CompressionOptions compressionOptions);
 434
 435   /**
 436    * Get the different options for compression algorithms
 437    *
 438    * @return The compression options
 439    */
 440   CompressionOptions compressionOptions();
 441
 442   /**
 443    * Default memtable memory budget used with the following methods:
 444    *
 445    * <ol>
 446    *   <li>{@link #optimizeLevelStyleCompaction()}</li>
 447    *   <li>{@link #optimizeUniversalStyleCompaction()}</li>
 448    * </ol>
 449    */
 450   long DEFAULT_COMPACTION_MEMTABLE_MEMORY_BUDGET = 512 * 1024 * 1024;
 451 }