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

Modifier and Type	Field and Description
protected Slice	iterateUpperBoundSlice_

Fields inherited from class org.rocksdb.RocksObject

nativeHandle_

Constructor Summary

Constructors

Constructor and Description
ReadOptions()
ReadOptions(ReadOptions other) Copy constructor.

Method Summary

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	iterateUpperBound() Defines the extent upto which the forward iterator can returns entries.
boolean	managed() Returns whether managed iterators will be used.
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	setIterateUpperBound(Slice iterateUpperBound) Defines the extent upto which the forward iterator can returns entries.
ReadOptions	setManaged(boolean managed) Specify to create a managed iterator -- a special iterator that uses less resources by having the ability to free its underlying resources on request.
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	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

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

Field Detail

iterateUpperBoundSlice_

protected Slice iterateUpperBoundSlice_

Constructor Detail

ReadOptions

public ReadOptions()

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

public boolean managed()

Returns whether managed iterators will be used.

Returns:

the setting of whether managed iterators will be used, by default false

setManaged

public ReadOptions setManaged(boolean managed)

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.

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.

setIterateUpperBound

public ReadOptions setIterateUpperBound(Slice iterateUpperBound)

Defines the extent upto which the forward iterator can returns entries. Once the bound is reached, Valid() will be false. iterate_upper_bound is exclusive ie the bound value is not a valid entry. If iterator_extractor is not null, the Seek target and iterator_upper_bound need to have the same prefix. This is because ordering is not guaranteed outside of prefix domain. There is no lower bound on the iterator. Default: nullptr

Parameters:

iterateUpperBound - Slice representing the upper bound

Returns:

the reference to the current ReadOptions.

iterateUpperBound

public Slice iterateUpperBound()

Defines the extent upto which the forward iterator can returns entries. Once the bound is reached, Valid() will be false. iterate_upper_bound is exclusive ie the bound value is not a valid entry. If iterator_extractor is not null, the Seek target and iterator_upper_bound need to have the same prefix. This is because ordering is not guaranteed outside of prefix domain. There is no lower bound on the iterator. Default: nullptr

Returns:

Slice representing current iterate_upper_bound setting, or null if one does not exist.

disposeInternal

protected final void disposeInternal(long handle)

Specified by:

disposeInternal in class RocksObject