Package org.rocksdb

Class ReadOptions

  • All Implemented Interfaces:
    java.lang.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++.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      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 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 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 returns 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 java.lang.Object

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

    • Constructor Detail

      • 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 Detail

      • 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.

      • 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 Not supported in ROCKSDB_LITE mode!
        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 Not supported in ROCKSDB_LITE mode!
        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 returns 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. Not supported in ROCKSDB_LITE mode, in the way that even with value true prefix mode is not used. 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. Not supported in ROCKSDB_LITE mode, in the way that even with value true prefix mode is not used. 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:
        iterStartTs()

      • 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:
        setIterStartTs(AbstractSlice)

      • 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