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

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

      • setIterStartSeqnum

        public ReadOptions setIterStartSeqnum​(long startSeqnum)
        Needed to support differential snapshots. Has 2 effects: 1) Iterator will skip all internal keys with seqnum < iter_start_seqnum 2) if this param > 0 iterator will return INTERNAL keys instead of user keys; e.g. return tombstones as well. Default: 0 (don't filter by seqnum, return user keys)
        Parameters:
        startSeqnum - the starting sequence number.
        Returns:
        the reference to the current ReadOptions.

      • iterStartSeqnum

        public long iterStartSeqnum()
        Returns the starting Sequence Number of any iterator. See setIterStartSeqnum(long).
        Returns:
        the starting sequence number of any iterator.