org.rocksdb

Class ReadOptions

java.lang.Object

org.rocksdb.AbstractNativeReference

org.rocksdb.AbstractImmutableNativeReference

org.rocksdb.RocksObject

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

Field Summary

Fields inherited from class org.rocksdb.RocksObject

nativeHandle_

Fields inherited from class org.rocksdb.AbstractImmutableNativeReference

owningHandle_

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
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.
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.
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.
long	iterStartSeqnum() Returns the starting Sequence Number of any iterator.
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	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	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	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	setIterStartSeqnum(long startSeqnum) Needed to support differential snapshots.
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	setTotalOrderSeek(boolean totalOrderSeek) Enable a total order seek regardless of index format (e.g.
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.
boolean	totalOrderSeek() Returns whether a total seek order will be used
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 org.rocksdb.AbstractNativeReference

dispose, finalize

Methods inherited from class java.lang.Object

clone, equals, 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.

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

disposeInternal

protected final void disposeInternal(long handle)

Specified by:

disposeInternal in class RocksObject