Package org.rocksdb

Class TtlDB

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

    • Method Detail

      • open

        public static TtlDB open​(Options options,
                         java.lang.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,
                         java.lang.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,
                         java.lang.String db_path,
                         java.util.List<ColumnFamilyDescriptor> columnFamilyDescriptors,
                         java.util.List<ColumnFamilyHandle> columnFamilyHandles,
                         java.util.List<java.lang.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.
        java.lang.IllegalArgumentException - when there is not a ttl value per given column family handle.

      • 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