Package org.rocksdb

Class ReadOptions

java.lang.Object
org.rocksdb.AbstractNativeReference
org.rocksdb.AbstractImmutableNativeReference
org.rocksdb.RocksObject
org.rocksdb.ReadOptions
All Implemented Interfaces:
AutoCloseable
public class ReadOptions extends RocksObject
The class that controls the get behavior.

Note that dispose() must be called before an Options instance become out-of-scope to release the allocated memory in c++.

  • Field Summary

    Fields inherited from class org.rocksdb.RocksObject

    nativeHandle_

    Fields inherited from class org.rocksdb.AbstractImmutableNativeReference

    owningHandle_

  • Constructor Summary

    Constructors
    Constructor
    Description
    ReadOptions()
     
    ReadOptions(boolean verifyChecksums, boolean fillCache)
     
    ReadOptions(ReadOptions other)
    Copy constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    asyncIo()
    If async_io is enabled, RocksDB will prefetch some of data asynchronously.
    boolean
    autoPrefixMode()
    When true, by default use total_order_seek = true, and RocksDB can selectively enable prefix seek mode if won't generate a different result from total_order_seek, based on seek key, and iterator upper bound.
    boolean
    backgroundPurgeOnIteratorCleanup()
    If true, when PurgeObsoleteFile is called in CleanupIteratorState, we schedule a background job in the flush job queue and delete obsolete files in background.
    long
    deadline()
    Deadline for completing an API call (Get/MultiGet/Seek/Next for now) in microseconds.
    protected final void
    disposeInternal(long handle)
     
    boolean
    fillCache()
    Fill the cache when loading the block-based sst formated db.
    boolean
    ignoreRangeDeletions()
    If true, keys deleted using the DeleteRange() API will be visible to readers until they are naturally deleted during compaction.
    long
    ioTimeout()
    A timeout in microseconds to be passed to the underlying FileSystem for reads.
    Slice
    iterateLowerBound()
    Returns the smallest key at which the backward iterator can return an entry.
    Slice
    iterateUpperBound()
    Returns the largest key at which the forward iterator can return an entry.
    Slice
    iterStartTs()
    Timestamp of operation.
    boolean
    managed()
    Deprecated.
    This options is not used anymore.
    long
    maxSkippableInternalKeys()
    A threshold for the number of keys that can be skipped before failing an iterator seek as incomplete.
    boolean
    pinData()
    Returns whether the blocks loaded by the iterator will be pinned in memory
    boolean
    prefixSameAsStart()
    Returns whether the iterator only iterates over the same prefix as the seek
    long
    readaheadSize()
    If non-zero, NewIterator will create a new table reader which performs reads of the given size.
    ReadTier
    readTier()
    Returns the current read tier.
    ReadOptions
    setAsyncIo(boolean asyncIo)
    If async_io is enabled, RocksDB will prefetch some of data asynchronously.
    ReadOptions
    setAutoPrefixMode(boolean mode)
    When true, by default use total_order_seek = true, and RocksDB can selectively enable prefix seek mode if won't generate a different result from total_order_seek, based on seek key, and iterator upper bound.
    ReadOptions
    setBackgroundPurgeOnIteratorCleanup(boolean backgroundPurgeOnIteratorCleanup)
    If true, when PurgeObsoleteFile is called in CleanupIteratorState, we schedule a background job in the flush job queue and delete obsolete files in background.
    ReadOptions
    setDeadline(long deadlineTime)
    Deadline for completing an API call (Get/MultiGet/Seek/Next for now) in microseconds.
    ReadOptions
    setFillCache(boolean fillCache)
    Fill the cache when loading the block-based sst formatted db.
    ReadOptions
    setIgnoreRangeDeletions(boolean ignoreRangeDeletions)
    If true, keys deleted using the DeleteRange() API will be visible to readers until they are naturally deleted during compaction.
    ReadOptions
    setIoTimeout(long ioTimeout)
    A timeout in microseconds to be passed to the underlying FileSystem for reads.
    ReadOptions
    setIterateLowerBound(AbstractSlice<?> iterateLowerBound)
    Defines the smallest key at which the backward iterator can return an entry.
    ReadOptions
    setIterateUpperBound(AbstractSlice<?> iterateUpperBound)
    Defines the extent up to which the forward iterator can return entries.
    ReadOptions
    setIterStartTs(AbstractSlice<?> iterStartTs)
    Timestamp of operation.
    ReadOptions
    setManaged(boolean managed)
    Deprecated.
    This options is not used anymore.
    ReadOptions
    setMaxSkippableInternalKeys(long maxSkippableInternalKeys)
    A threshold for the number of keys that can be skipped before failing an iterator seek as incomplete.
    ReadOptions
    setPinData(boolean pinData)
    Keep the blocks loaded by the iterator pinned in memory as long as the iterator is not deleted, If used when reading from tables created with BlockBasedTableOptions::use_delta_encoding = false, Iterator's property "rocksdb.iterator.is-key-pinned" is guaranteed to return 1.
    ReadOptions
    setPrefixSameAsStart(boolean prefixSameAsStart)
    Enforce that the iterator only iterates over the same prefix as the seek.
    ReadOptions
    setReadaheadSize(long readaheadSize)
    If non-zero, NewIterator will create a new table reader which performs reads of the given size.
    ReadOptions
    setReadTier(ReadTier readTier)
    Specify if this read request should process data that ALREADY resides on a particular cache.
    ReadOptions
    setSnapshot(Snapshot snapshot)
    If "snapshot" is non-nullptr, read as of the supplied snapshot (which must belong to the DB that is being read and which must not have been released).
    ReadOptions
    setTableFilter(AbstractTableFilter tableFilter)
    A callback to determine whether relevant keys for this scan exist in a given table based on the table's properties.
    ReadOptions
    setTailing(boolean tailing)
    Specify to create a tailing iterator -- a special iterator that has a view of the complete database (i.e.
    ReadOptions
    setTimestamp(AbstractSlice<?> timestamp)
    Timestamp of operation.
    ReadOptions
    setTotalOrderSeek(boolean totalOrderSeek)
    Enable a total order seek regardless of index format (e.g.
    ReadOptions
    setValueSizeSoftLimit(long valueSizeSoftLimit)
    It limits the maximum cumulative value size of the keys in batch while reading through MultiGet.
    ReadOptions
    setVerifyChecksums(boolean verifyChecksums)
    If true, all data read from underlying storage will be verified against corresponding checksums.
    Snapshot
    snapshot()
    Returns the currently assigned Snapshot instance.
    boolean
    tailing()
    Specify to create a tailing iterator -- a special iterator that has a view of the complete database (i.e.
    Slice
    timestamp()
    Timestamp of operation.
    boolean
    totalOrderSeek()
    Returns whether a total seek order will be used
    long
    valueSizeSoftLimit()
    It limits the maximum cumulative value size of the keys in batch while reading through MultiGet.
    boolean
    verifyChecksums()
    If true, all data read from underlying storage will be verified against corresponding checksums.

    Methods inherited from class org.rocksdb.RocksObject

    disposeInternal, getNativeHandle

    Methods inherited from class org.rocksdb.AbstractImmutableNativeReference

    close, disOwnNativeHandle, isOwningHandle

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • ReadOptions

      public ReadOptions()

    • ReadOptions

      public ReadOptions(boolean verifyChecksums, boolean fillCache)
      Parameters:
      verifyChecksums - verification will be performed on every read when set to true
      fillCache - if true, then fill-cache behavior will be performed.

    • ReadOptions

      public ReadOptions(ReadOptions other)
      Copy constructor.

      NOTE: This does a shallow copy, which means snapshot, iterate_upper_bound and other pointers will be cloned!

      Parameters:
      other - The ReadOptions to copy.

  • Method Details

    • verifyChecksums

      public boolean verifyChecksums()
      If true, all data read from underlying storage will be verified against corresponding checksums. Default: true
      Returns:
      true if checksum verification is on.

    • setVerifyChecksums

      public ReadOptions setVerifyChecksums(boolean verifyChecksums)
      If true, all data read from underlying storage will be verified against corresponding checksums. Default: true
      Parameters:
      verifyChecksums - if true, then checksum verification will be performed on every read.
      Returns:
      the reference to the current ReadOptions.

    • fillCache

      public boolean fillCache()
      Fill the cache when loading the block-based sst formated db. Callers may wish to set this field to false for bulk scans. Default: true
      Returns:
      true if the fill-cache behavior is on.

    • setFillCache

      public ReadOptions setFillCache(boolean fillCache)
      Fill the cache when loading the block-based sst formatted db. Callers may wish to set this field to false for bulk scans. Default: true
      Parameters:
      fillCache - if true, then fill-cache behavior will be performed.
      Returns:
      the reference to the current ReadOptions.

    • snapshot

      public Snapshot snapshot()
      Returns the currently assigned Snapshot instance.
      Returns:
      the Snapshot assigned to this instance. If no Snapshot is assigned null.

    • setSnapshot

      public ReadOptions setSnapshot(Snapshot snapshot)

      If "snapshot" is non-nullptr, read as of the supplied snapshot (which must belong to the DB that is being read and which must not have been released). If "snapshot" is nullptr, use an implicit snapshot of the state at the beginning of this read operation.

      Default: null

      Parameters:
      snapshot - Snapshot instance
      Returns:
      the reference to the current ReadOptions.

    • readTier

      public ReadTier readTier()
      Returns the current read tier.
      Returns:
      the read tier in use, by default ReadTier.READ_ALL_TIER

    • setReadTier

      public ReadOptions setReadTier(ReadTier readTier)
      Specify if this read request should process data that ALREADY resides on a particular cache. If the required data is not found at the specified cache, then RocksDBException is thrown.
      Parameters:
      readTier - ReadTier instance
      Returns:
      the reference to the current ReadOptions.

    • tailing

      public boolean tailing()
      Specify to create a tailing iterator -- a special iterator that has a view of the complete database (i.e. it can also be used to read newly added data) and is optimized for sequential reads. It will return records that were inserted into the database after the creation of the iterator. Default: false
      Returns:
      true if tailing iterator is enabled.

    • setTailing

      public ReadOptions setTailing(boolean tailing)
      Specify to create a tailing iterator -- a special iterator that has a view of the complete database (i.e. it can also be used to read newly added data) and is optimized for sequential reads. It will return records that were inserted into the database after the creation of the iterator. Default: false
      Parameters:
      tailing - if true, then tailing iterator will be enabled.
      Returns:
      the reference to the current ReadOptions.

    • managed

      @Deprecated public boolean managed()
      Deprecated.
      This options is not used anymore.
      Returns whether managed iterators will be used.
      Returns:
      the setting of whether managed iterators will be used, by default false

    • setManaged

      @Deprecated public ReadOptions setManaged(boolean managed)
      Deprecated.
      This options is not used anymore.
      Specify to create a managed iterator -- a special iterator that uses less resources by having the ability to free its underlying resources on request.
      Parameters:
      managed - if true, then managed iterators will be enabled.
      Returns:
      the reference to the current ReadOptions.

    • totalOrderSeek

      public boolean totalOrderSeek()
      Returns whether a total seek order will be used
      Returns:
      the setting of whether a total seek order will be used

    • setTotalOrderSeek

      public ReadOptions setTotalOrderSeek(boolean totalOrderSeek)
      Enable a total order seek regardless of index format (e.g. hash index) used in the table. Some table format (e.g. plain table) may not support this option.
      Parameters:
      totalOrderSeek - if true, then total order seek will be enabled.
      Returns:
      the reference to the current ReadOptions.

    • prefixSameAsStart

      public boolean prefixSameAsStart()
      Returns whether the iterator only iterates over the same prefix as the seek
      Returns:
      the setting of whether the iterator only iterates over the same prefix as the seek, default is false

    • setPrefixSameAsStart

      public ReadOptions setPrefixSameAsStart(boolean prefixSameAsStart)
      Enforce that the iterator only iterates over the same prefix as the seek. This option is effective only for prefix seeks, i.e. prefix_extractor is non-null for the column family and totalOrderSeek() is false. Unlike iterate_upper_bound, #setPrefixSameAsStart(boolean) only works within a prefix but in both directions.
      Parameters:
      prefixSameAsStart - if true, then the iterator only iterates over the same prefix as the seek
      Returns:
      the reference to the current ReadOptions.

    • pinData

      public boolean pinData()
      Returns whether the blocks loaded by the iterator will be pinned in memory
      Returns:
      the setting of whether the blocks loaded by the iterator will be pinned in memory

    • setPinData

      public ReadOptions setPinData(boolean pinData)
      Keep the blocks loaded by the iterator pinned in memory as long as the iterator is not deleted, If used when reading from tables created with BlockBasedTableOptions::use_delta_encoding = false, Iterator's property "rocksdb.iterator.is-key-pinned" is guaranteed to return 1.
      Parameters:
      pinData - if true, the blocks loaded by the iterator will be pinned
      Returns:
      the reference to the current ReadOptions.

    • backgroundPurgeOnIteratorCleanup

      public boolean backgroundPurgeOnIteratorCleanup()
      If true, when PurgeObsoleteFile is called in CleanupIteratorState, we schedule a background job in the flush job queue and delete obsolete files in background.

      Default: false

      Returns:
      true when PurgeObsoleteFile is called in CleanupIteratorState

    • setBackgroundPurgeOnIteratorCleanup

      public ReadOptions setBackgroundPurgeOnIteratorCleanup(boolean backgroundPurgeOnIteratorCleanup)
      If true, when PurgeObsoleteFile is called in CleanupIteratorState, we schedule a background job in the flush job queue and delete obsolete files in background.

      Default: false

      Parameters:
      backgroundPurgeOnIteratorCleanup - true when PurgeObsoleteFile is called in CleanupIteratorState
      Returns:
      the reference to the current ReadOptions.

    • readaheadSize

      public long readaheadSize()
      If non-zero, NewIterator will create a new table reader which performs reads of the given size. Using a large size (> 2MB) can improve the performance of forward iteration on spinning disks.

      Default: 0

      Returns:
      The readahead size is bytes

    • setReadaheadSize

      public ReadOptions setReadaheadSize(long readaheadSize)
      If non-zero, NewIterator will create a new table reader which performs reads of the given size. Using a large size (> 2MB) can improve the performance of forward iteration on spinning disks.

      Default: 0

      Parameters:
      readaheadSize - The readahead size is bytes
      Returns:
      the reference to the current ReadOptions.

    • maxSkippableInternalKeys

      public long maxSkippableInternalKeys()
      A threshold for the number of keys that can be skipped before failing an iterator seek as incomplete.
      Returns:
      the number of keys that can be skipped before failing an iterator seek as incomplete.

    • setMaxSkippableInternalKeys

      public ReadOptions setMaxSkippableInternalKeys(long maxSkippableInternalKeys)
      A threshold for the number of keys that can be skipped before failing an iterator seek as incomplete. The default value of 0 should be used to never fail a request as incomplete, even on skipping too many keys.

      Default: 0

      Parameters:
      maxSkippableInternalKeys - the number of keys that can be skipped before failing an iterator seek as incomplete.
      Returns:
      the reference to the current ReadOptions.

    • ignoreRangeDeletions

      public boolean ignoreRangeDeletions()
      If true, keys deleted using the DeleteRange() API will be visible to readers until they are naturally deleted during compaction. This improves read performance in DBs with many range deletions.

      Default: false

      Returns:
      true if keys deleted using the DeleteRange() API will be visible

    • setIgnoreRangeDeletions

      public ReadOptions setIgnoreRangeDeletions(boolean ignoreRangeDeletions)
      If true, keys deleted using the DeleteRange() API will be visible to readers until they are naturally deleted during compaction. This improves read performance in DBs with many range deletions.

      Default: false

      Parameters:
      ignoreRangeDeletions - true if keys deleted using the DeleteRange() API should be visible
      Returns:
      the reference to the current ReadOptions.

    • setIterateLowerBound

      public ReadOptions setIterateLowerBound(AbstractSlice<?> iterateLowerBound)
      Defines the smallest key at which the backward iterator can return an entry. Once the bound is passed, AbstractRocksIterator.isValid() will be false.

      The lower bound is inclusive i.e. the bound value is a valid entry.

      If prefix_extractor is not null, the Seek target and `iterate_lower_bound` need to have the same prefix. This is because ordering is not guaranteed outside of prefix domain.

      Default: null

      Parameters:
      iterateLowerBound - Slice representing the lower bound
      Returns:
      the reference to the current ReadOptions.

    • iterateLowerBound

      public Slice iterateLowerBound()
      Returns the smallest key at which the backward iterator can return an entry.

      The lower bound is inclusive i.e. the bound value is a valid entry.

      Returns:
      the smallest key, or null if there is no lower bound defined.

    • setIterateUpperBound

      public ReadOptions setIterateUpperBound(AbstractSlice<?> iterateUpperBound)
      Defines the extent up to which the forward iterator can return entries. Once the bound is reached, AbstractRocksIterator.isValid() will be false.

      The upper bound is exclusive i.e. the bound value is not a valid entry.

      If prefix_extractor is not null, the Seek target and iterate_upper_bound need to have the same prefix. This is because ordering is not guaranteed outside of prefix domain.

      Default: null

      Parameters:
      iterateUpperBound - Slice representing the upper bound
      Returns:
      the reference to the current ReadOptions.

    • iterateUpperBound

      public Slice iterateUpperBound()
      Returns the largest key at which the forward iterator can return an entry.

      The upper bound is exclusive i.e. the bound value is not a valid entry.

      Returns:
      the largest key, or null if there is no upper bound defined.

    • setTableFilter

      public ReadOptions setTableFilter(AbstractTableFilter tableFilter)
      A callback to determine whether relevant keys for this scan exist in a given table based on the table's properties. The callback is passed the properties of each table during iteration. If the callback returns false, the table will not be scanned. This option only affects Iterators and has no impact on point lookups.

      Default: null (every table will be scanned)

      Parameters:
      tableFilter - the table filter for the callback.
      Returns:
      the reference to the current ReadOptions.

    • autoPrefixMode

      public boolean autoPrefixMode()
      When true, by default use total_order_seek = true, and RocksDB can selectively enable prefix seek mode if won't generate a different result from total_order_seek, based on seek key, and iterator upper bound. Default: false
      Returns:
      true if auto prefix mode is set.

    • setAutoPrefixMode

      public ReadOptions setAutoPrefixMode(boolean mode)
      When true, by default use total_order_seek = true, and RocksDB can selectively enable prefix seek mode if won't generate a different result from total_order_seek, based on seek key, and iterator upper bound. Default: false
      Parameters:
      mode - auto prefix mode
      Returns:
      the reference to the current ReadOptions.

    • timestamp

      public Slice timestamp()
      Timestamp of operation. Read should return the latest data visible to the specified timestamp. All timestamps of the same database must be of the same length and format. The user is responsible for providing a customized compare function via Comparator to order >key, timestamp> tuples. For iterator, iter_start_ts is the lower bound (older) and timestamp serves as the upper bound. Versions of the same record that fall in the timestamp range will be returned. If iter_start_ts is nullptr, only the most recent version visible to timestamp is returned. The user-specified timestamp feature is still under active development, and the API is subject to change.

      Default: null

      Returns:
      Reference to timestamp or null if there is no timestamp defined.
      See Also:

    • setTimestamp

      public ReadOptions setTimestamp(AbstractSlice<?> timestamp)
      Timestamp of operation. Read should return the latest data visible to the specified timestamp. All timestamps of the same database must be of the same length and format. The user is responsible for providing a customized compare function via Comparator to order <key, timestamp> tuples. For iterator, iter_start_ts is the lower bound (older) and timestamp serves as the upper bound. Versions of the same record that fall in the timestamp range will be returned. If iter_start_ts is nullptr, only the most recent version visible to timestamp is returned. The user-specified timestamp feature is still under active development, and the API is subject to change.

      Default: null

      Parameters:
      timestamp - Slice representing the timestamp
      Returns:
      the reference to the current ReadOptions.
      See Also:

    • iterStartTs

      public Slice iterStartTs()
      Timestamp of operation. Read should return the latest data visible to the specified timestamp. All timestamps of the same database must be of the same length and format. The user is responsible for providing a customized compare function via Comparator to order <key, timestamp> tuples. For iterator, iter_start_ts is the lower bound (older) and timestamp serves as the upper bound. Versions of the same record that fall in the timestamp range will be returned. If iter_start_ts is nullptr, only the most recent version visible to timestamp is returned. The user-specified timestamp feature is still under active development, and the API is subject to change.

      Default: null

      Returns:
      Reference to lower bound timestamp or null if there is no lower bound timestamp defined.

    • setIterStartTs

      public ReadOptions setIterStartTs(AbstractSlice<?> iterStartTs)
      Timestamp of operation. Read should return the latest data visible to the specified timestamp. All timestamps of the same database must be of the same length and format. The user is responsible for providing a customized compare function via Comparator to order <key, timestamp> tuples. For iterator, iter_start_ts is the lower bound (older) and timestamp serves as the upper bound. Versions of the same record that fall in the timestamp range will be returned. If iter_start_ts is nullptr, only the most recent version visible to timestamp is returned. The user-specified timestamp feature is still under active development, and the API is subject to change.

      Default: null

      Parameters:
      iterStartTs - Reference to lower bound timestamp or null if there is no lower bound timestamp defined
      Returns:
      the reference to the current ReadOptions.

    • deadline

      public long deadline()
      Deadline for completing an API call (Get/MultiGet/Seek/Next for now) in microseconds. It should be set to microseconds since epoch, i.e, gettimeofday or equivalent plus allowed duration in microseconds. The best way is to use env->NowMicros() + some timeout. This is best efforts. The call may exceed the deadline if there is IO involved and the file system doesn't support deadlines, or due to checking for deadline periodically rather than for every key if processing a batch
      Returns:
      deadline time in microseconds

    • setDeadline

      public ReadOptions setDeadline(long deadlineTime)
      Deadline for completing an API call (Get/MultiGet/Seek/Next for now) in microseconds. It should be set to microseconds since epoch, i.e, gettimeofday or equivalent plus allowed duration in microseconds. The best way is to use env->NowMicros() + some timeout. This is best efforts. The call may exceed the deadline if there is IO involved and the file system doesn't support deadlines, or due to checking for deadline periodically rather than for every key if processing a batch
      Parameters:
      deadlineTime - deadline time in microseconds.
      Returns:
      the reference to the current ReadOptions.

    • ioTimeout

      public long ioTimeout()
      A timeout in microseconds to be passed to the underlying FileSystem for reads. As opposed to deadline, this determines the timeout for each individual file read request. If a MultiGet/Get/Seek/Next etc call results in multiple reads, each read can last up to io_timeout us.
      Returns:
      ioTimeout time in microseconds

    • setIoTimeout

      public ReadOptions setIoTimeout(long ioTimeout)
      A timeout in microseconds to be passed to the underlying FileSystem for reads. As opposed to deadline, this determines the timeout for each individual file read request. If a MultiGet/Get/Seek/Next etc call results in multiple reads, each read can last up to io_timeout us.
      Parameters:
      ioTimeout - time in microseconds.
      Returns:
      the reference to the current ReadOptions.

    • valueSizeSoftLimit

      public long valueSizeSoftLimit()
      It limits the maximum cumulative value size of the keys in batch while reading through MultiGet. Once the cumulative value size exceeds this soft limit then all the remaining keys are returned with status Aborted.

      Default: std::numeric_limits<uint64_t>::max()

      Returns:
      actual valueSizeSofLimit

    • setValueSizeSoftLimit

      public ReadOptions setValueSizeSoftLimit(long valueSizeSoftLimit)
      It limits the maximum cumulative value size of the keys in batch while reading through MultiGet. Once the cumulative value size exceeds this soft limit then all the remaining keys are returned with status Aborted.

      Default: std::numeric_limits<uint64_t>::max()

      Parameters:
      valueSizeSoftLimit - the maximum cumulative value size of the keys
      Returns:
      the reference to the current ReadOptions

    • asyncIo

      @Experimental("Caution: this option is experimental") public boolean asyncIo()
      If async_io is enabled, RocksDB will prefetch some of data asynchronously. RocksDB apply it if reads are sequential and its internal automatic prefetching.

      Default: false

      Returns:
      true if async_io is enabled.

    • setAsyncIo

      @Experimental("Caution: this option is experimental") public ReadOptions setAsyncIo(boolean asyncIo)
      If async_io is enabled, RocksDB will prefetch some of data asynchronously. RocksDB apply it if reads are sequential and its internal automatic prefetching.

      Parameters:
      asyncIo - async_io enabled or not.
      Returns:
      the reference to the current ReadOptions.

    • disposeInternal

      protected final void disposeInternal(long handle)
      Specified by:
      disposeInternal in class RocksObject