org.rocksdb

Class TtlDB

java.lang.Object

org.rocksdb.AbstractNativeReference

org.rocksdb.AbstractImmutableNativeReference

org.rocksdb.RocksObject

org.rocksdb.RocksDB

org.rocksdb.TtlDB

All Implemented Interfaces:

AutoCloseable

public class TtlDB
extends RocksDB

Database with TTL support.

Use case

This API should be used to open the db when key-values inserted are meant to be removed from the db in a non-strict 'ttl' amount of time Therefore, this guarantees that key-values inserted will remain in the db for >= ttl amount of time and the db will make efforts to remove the key-values as soon as possible after ttl seconds of their insertion.

Behaviour

TTL is accepted in seconds (int32_t)Timestamp(creation) is suffixed to values in Put internally Expired TTL values deleted in compaction only:(Timestamp+ttl<time_now) Get/Iterator may return expired entries(compaction not run on them yet) Different TTL may be used during different Opens

Example

• Open1 at t=0 with ttl=4 and insert k1,k2, close at t=2
• Open2 at t=3 with ttl=5. Now k1,k2 should be deleted at t>=5

read_only=true opens in the usual read-only mode. Compactions will not be triggered(neither manual nor automatic), so no expired entries removed

Constraints

Not specifying/passing or non-positive TTL behaves like TTL = infinity

!!!WARNING!!!

Calling DB::Open directly to re-open a db created by this API will get corrupt values(timestamp suffixed) and no ttl effect will be there during the second Open, so use this API consistently to open the db Be careful when passing ttl with a small positive value because the whole database may be deleted in a small amount of time.

Nested Class Summary

Nested classes/interfaces inherited from class org.rocksdb.RocksDB

RocksDB.CountAndSize, RocksDB.LiveFiles, RocksDB.Version

Field Summary

Fields inherited from class org.rocksdb.RocksDB

DEFAULT_COLUMN_FAMILY, NOT_FOUND, options_

Fields inherited from class org.rocksdb.RocksObject

nativeHandle_

Fields inherited from class org.rocksdb.AbstractImmutableNativeReference

owningHandle_

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	TtlDB(long nativeHandle) A protected constructor that will be used in the static factory method open(Options, String, int, boolean) and open(DBOptions, String, java.util.List, java.util.List, java.util.List, boolean).

Method Summary

Modifier and Type	Method and Description
void	close() Close the TtlDB instance and release resource.
void	closeE() Close the TtlDB instance and release resource.
ColumnFamilyHandle	createColumnFamilyWithTtl(ColumnFamilyDescriptor columnFamilyDescriptor, int ttl) Creates a new ttl based column family with a name defined in given ColumnFamilyDescriptor and allocates a ColumnFamilyHandle within an internal structure.
protected void	disposeInternal(long handle)
static TtlDB	open(DBOptions options, String db_path, List<ColumnFamilyDescriptor> columnFamilyDescriptors, List<ColumnFamilyHandle> columnFamilyHandles, List<Integer> ttlValues, boolean readOnly) Opens a TtlDB.
static TtlDB	open(Options options, String db_path) Opens a TtlDB.
static TtlDB	open(Options options, String db_path, int ttl, boolean readOnly) Opens a TtlDB.

Methods inherited from class org.rocksdb.RocksDB

cancelAllBackgroundWork, compactFiles, compactFiles, compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, compactRange, continueBackgroundWork, createColumnFamilies, createColumnFamilies, createColumnFamily, delete, delete, delete, delete, delete, delete, delete, delete, delete, delete, deleteFile, deleteFilesInRanges, deleteRange, deleteRange, deleteRange, deleteRange, destroyColumnFamilyHandle, destroyDB, disableFileDeletions, dropColumnFamilies, dropColumnFamily, enableAutoCompaction, enableFileDeletions, endTrace, flush, flush, flush, flushWal, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, get, getAggregatedLongProperty, getApproximateMemTableStats, getApproximateMemTableStats, getApproximateSizes, getApproximateSizes, getColumnFamilyMetaData, getColumnFamilyMetaData, getDefaultColumnFamily, getEnv, getLatestSequenceNumber, getLiveFiles, getLiveFiles, getLiveFilesMetaData, getLongProperty, getLongProperty, getMapProperty, getMapProperty, getName, getPropertiesOfAllTables, getPropertiesOfAllTables, getPropertiesOfTablesInRange, getPropertiesOfTablesInRange, getProperty, getProperty, getSnapshot, getSortedWalFiles, getUpdatesSince, ingestExternalFile, ingestExternalFile, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, keyMayExist, level0StopWriteTrigger, level0StopWriteTrigger, listColumnFamilies, loadLibrary, loadLibrary, maxMemCompactionLevel, maxMemCompactionLevel, merge, merge, merge, merge, merge, merge, merge, merge, multiGet, multiGet, multiGet, multiGet, multiGetAsList, multiGetAsList, multiGetAsList, multiGetAsList, newIterator, newIterator, newIterator, newIterator, newIterators, newIterators, numberLevels, numberLevels, open, open, open, openAsSecondary, openAsSecondary, openReadOnly, openReadOnly, openReadOnly, openReadOnly, openReadOnly, openReadOnly, pauseBackgroundWork, promoteL0, promoteL0, put, put, put, put, put, put, put, put, put, put, releaseSnapshot, remove, remove, remove, remove, resetStats, rocksdbVersion, setDBOptions, setOptions, setOptions, setPreserveDeletesSequenceNumber, singleDelete, singleDelete, singleDelete, singleDelete, startTrace, storeOptionsInstance, suggestCompactRange, suggestCompactRange, syncWal, tryCatchUpWithPrimary, verifyChecksum, write, write

Methods inherited from class org.rocksdb.RocksObject

disposeInternal, getNativeHandle

Methods inherited from class org.rocksdb.AbstractImmutableNativeReference

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

TtlDB

protected TtlDB(long nativeHandle)

A protected constructor that will be used in the static factory method open(Options, String, int, boolean) and open(DBOptions, String, java.util.List, java.util.List, java.util.List, boolean).

Parameters:

nativeHandle - The native handle of the C++ TtlDB object

Method Detail

open

public static TtlDB open(Options options,
                         String db_path)
                  throws RocksDBException

Opens a TtlDB.

Database is opened in read-write mode without default TTL.

Parameters:

options - Options instance.

db_path - path to database.

Returns:

TtlDB instance.

Throws:

RocksDBException - thrown if an error occurs within the native part of the library.

open

public static TtlDB open(Options options,
                         String db_path,
                         int ttl,
                         boolean readOnly)
                  throws RocksDBException

Opens a TtlDB.

Parameters:

options - Options instance.

db_path - path to database.

ttl - time to live for new entries.

readOnly - boolean value indicating if database if db is opened read-only.

Returns:

TtlDB instance.

Throws:

RocksDBException - thrown if an error occurs within the native part of the library.

open

public static TtlDB open(DBOptions options,
                         String db_path,
                         List<ColumnFamilyDescriptor> columnFamilyDescriptors,
                         List<ColumnFamilyHandle> columnFamilyHandles,
                         List<Integer> ttlValues,
                         boolean readOnly)
                  throws RocksDBException

Opens a TtlDB.

Parameters:

options - Options instance.

db_path - path to database.

columnFamilyDescriptors - list of column family descriptors

columnFamilyHandles - will be filled with ColumnFamilyHandle instances on open.

ttlValues - time to live values per column family handle

readOnly - boolean value indicating if database if db is opened read-only.

Returns:

TtlDB instance.

Throws:

RocksDBException - thrown if an error occurs within the native part of the library.

IllegalArgumentException - when there is not a ttl value per given column family handle.

closeE

public void closeE()
            throws RocksDBException

Close the TtlDB instance and release resource.

This is similar to close() except that it throws an exception if any error occurs. This will not fsync the WAL files. If syncing is required, the caller must first call RocksDB.syncWal() or RocksDB.write(WriteOptions, WriteBatch) using an empty write batch with WriteOptions.setSync(boolean) set to true. See also close().

Overrides:

closeE in class RocksDB

Throws:

RocksDBException - if an error occurs whilst closing.

close

public void close()

Close the TtlDB instance and release resource.

This will not fsync the WAL files. If syncing is required, the caller must first call RocksDB.syncWal() or RocksDB.write(WriteOptions, WriteBatch) using an empty write batch with WriteOptions.setSync(boolean) set to true. See also close().

Specified by:

close in interface AutoCloseable

Overrides:

close in class RocksDB

createColumnFamilyWithTtl

public ColumnFamilyHandle createColumnFamilyWithTtl(ColumnFamilyDescriptor columnFamilyDescriptor,
                                                    int ttl)
                                             throws RocksDBException

Creates a new ttl based column family with a name defined in given ColumnFamilyDescriptor and allocates a ColumnFamilyHandle within an internal structure.

The ColumnFamilyHandle is automatically disposed with DB disposal.

Parameters:

columnFamilyDescriptor - column family to be created.

ttl - TTL to set for this column family.

Returns:

ColumnFamilyHandle instance.

Throws:

RocksDBException - thrown if error happens in underlying native library.

disposeInternal

protected void disposeInternal(long handle)

Overrides:

disposeInternal in class RocksDB