Package org.rocksdb

Interface WriteBatchInterface

All Known Implementing Classes:
AbstractWriteBatch, WriteBatch, WriteBatchWithIndex
public interface WriteBatchInterface

Defines the interface for a Write Batch which holds a collection of updates to apply atomically to a DB.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Clear all updates buffered in this batch
    int
    count()
    Returns the number of updates in the batch.
    void
    delete(byte[] key)
    If the database contains a mapping for "key", erase it.
    void
    delete(ByteBuffer key)
    If column family contains a mapping for "key", erase it.
    void
    delete(ColumnFamilyHandle columnFamilyHandle, byte[] key)
    If column family contains a mapping for "key", erase it.
    void
    delete(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key)
    If column family contains a mapping for "key", erase it.
    void
    deleteRange(byte[] beginKey, byte[] endKey)
    Removes the database entries in the range ["beginKey", "endKey"), i.e., including "beginKey" and excluding "endKey".
    void
    deleteRange(ColumnFamilyHandle columnFamilyHandle, byte[] beginKey, byte[] endKey)
    Removes the database entries in the range ["beginKey", "endKey"), i.e., including "beginKey" and excluding "endKey".
    WriteBatch
    getWriteBatch()
    Get the underlying Write Batch.
    void
    merge(byte[] key, byte[] value)
    Merge "value" with the existing value of "key" in the database.
    void
    merge(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value)
    Merge "value" with the existing value of "key" in given column family.
    void
    popSavePoint()
    Pop the most recent save point.
    void
    put(byte[] key, byte[] value)
    Store the mapping "key->value" in the database.
    void
    put(ByteBuffer key, ByteBuffer value)
    Store the mapping "key->value" within given column family.
    void
    put(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value)
    Store the mapping "key->value" within given column family.
    void
    put(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value)
    Store the mapping "key->value" within given column family.
    void
    putLogData(byte[] blob)
    Append a blob of arbitrary size to the records in this batch.
    void
    rollbackToSavePoint()
    Remove all entries in this batch (Put, Merge, Delete, PutLogData) since the most recent call to SetSavePoint() and removes the most recent save point.
    void
    setMaxBytes(long maxBytes)
    Set the maximum size of the write batch.
    void
    setSavePoint()
    Records the state of the batch for future calls to RollbackToSavePoint().
    void
    singleDelete(byte[] key)
    Remove the database entry for key.
    void
    singleDelete(ColumnFamilyHandle columnFamilyHandle, byte[] key)
    Remove the database entry for key.

  • Method Details

    • count

      int count()
      Returns the number of updates in the batch.
      Returns:
      number of items in WriteBatch

    • put

      void put(byte[] key, byte[] value) throws RocksDBException

      Store the mapping "key->value" in the database.

      Parameters:
      key - the specified key to be inserted.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • put

      void put(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value) throws RocksDBException

      Store the mapping "key->value" within given column family.

      Parameters:
      columnFamilyHandle - ColumnFamilyHandle instance
      key - the specified key to be inserted.
      value - the value associated with the specified key.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • put

      void put(ByteBuffer key, ByteBuffer value) throws RocksDBException

      Store the mapping "key->value" within given column family.

      Parameters:
      key - the specified key to be inserted. It is using position and limit. Supports direct buffer only.
      value - the value associated with the specified key. It is using position and limit. Supports direct buffer only.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • put

      void put(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key, ByteBuffer value) throws RocksDBException

      Store the mapping "key->value" within given column family.

      Parameters:
      columnFamilyHandle - ColumnFamilyHandle instance
      key - the specified key to be inserted. It is using position and limit. Supports direct buffer only.
      value - the value associated with the specified key. It is using position and limit. Supports direct buffer only.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • merge

      void merge(byte[] key, byte[] value) throws RocksDBException

      Merge "value" with the existing value of "key" in the database. "key->merge(existing, value)"

      Parameters:
      key - the specified key to be merged.
      value - the value to be merged with the current value for the specified key.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • merge

      void merge(ColumnFamilyHandle columnFamilyHandle, byte[] key, byte[] value) throws RocksDBException

      Merge "value" with the existing value of "key" in given column family. "key->merge(existing, value)"

      Parameters:
      columnFamilyHandle - ColumnFamilyHandle instance
      key - the specified key to be merged.
      value - the value to be merged with the current value for the specified key.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • delete

      void delete(byte[] key) throws RocksDBException

      If the database contains a mapping for "key", erase it. Else do nothing.

      Parameters:
      key - Key to delete within database
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • delete

      void delete(ColumnFamilyHandle columnFamilyHandle, byte[] key) throws RocksDBException

      If column family contains a mapping for "key", erase it. Else do nothing.

      Parameters:
      columnFamilyHandle - ColumnFamilyHandle instance
      key - Key to delete within database
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • delete

      void delete(ByteBuffer key) throws RocksDBException

      If column family contains a mapping for "key", erase it. Else do nothing.

      Parameters:
      key - Key to delete within database. It is using position and limit. Supports direct buffer only.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • delete

      void delete(ColumnFamilyHandle columnFamilyHandle, ByteBuffer key) throws RocksDBException

      If column family contains a mapping for "key", erase it. Else do nothing.

      Parameters:
      columnFamilyHandle - ColumnFamilyHandle instance
      key - Key to delete within database. It is using position and limit. Supports direct buffer only.
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • singleDelete

      @Experimental("Performance optimization for a very specific workload") void singleDelete(byte[] key) throws RocksDBException
      Remove the database entry for key. Requires that the key exists and was not overwritten. It is not an error if the key did not exist in the database.

      If a key is overwritten (by calling put(byte[], byte[]) multiple times), then the result of calling SingleDelete() on this key is undefined. SingleDelete() only behaves correctly if there has been only one Put() for this key since the previous call to SingleDelete() for this key.

      This feature is currently an experimental performance optimization for a very specific workload. It is up to the caller to ensure that SingleDelete is only used for a key that is not deleted using Delete() or written using Merge(). Mixing SingleDelete operations with Deletes and Merges can result in undefined behavior.

      Parameters:
      key - Key to delete within database
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • singleDelete

      @Experimental("Performance optimization for a very specific workload") void singleDelete(ColumnFamilyHandle columnFamilyHandle, byte[] key) throws RocksDBException
      Remove the database entry for key. Requires that the key exists and was not overwritten. It is not an error if the key did not exist in the database.

      If a key is overwritten (by calling put(byte[], byte[]) multiple times), then the result of calling SingleDelete() on this key is undefined. SingleDelete() only behaves correctly if there has been only one Put() for this key since the previous call to SingleDelete() for this key.

      This feature is currently an experimental performance optimization for a very specific workload. It is up to the caller to ensure that SingleDelete is only used for a key that is not deleted using Delete() or written using Merge(). Mixing SingleDelete operations with Deletes and Merges can result in undefined behavior.

      Parameters:
      columnFamilyHandle - The column family to delete the key from
      key - Key to delete within database
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • deleteRange

      void deleteRange(byte[] beginKey, byte[] endKey) throws RocksDBException
      Removes the database entries in the range ["beginKey", "endKey"), i.e., including "beginKey" and excluding "endKey". a non-OK status on error. It is not an error if no keys exist in the range ["beginKey", "endKey").

      Delete the database entry (if any) for "key". Returns OK on success, and a non-OK status on error. It is not an error if "key" did not exist in the database.

      Parameters:
      beginKey - First key to delete within database (included)
      endKey - Last key to delete within database (excluded)
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • deleteRange

      void deleteRange(ColumnFamilyHandle columnFamilyHandle, byte[] beginKey, byte[] endKey) throws RocksDBException
      Removes the database entries in the range ["beginKey", "endKey"), i.e., including "beginKey" and excluding "endKey". a non-OK status on error. It is not an error if no keys exist in the range ["beginKey", "endKey").

      Delete the database entry (if any) for "key". Returns OK on success, and a non-OK status on error. It is not an error if "key" did not exist in the database.

      Parameters:
      columnFamilyHandle - ColumnFamilyHandle instance
      beginKey - First key to delete within database (included)
      endKey - Last key to delete within database (excluded)
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • putLogData

      void putLogData(byte[] blob) throws RocksDBException
      Append a blob of arbitrary size to the records in this batch. The blob will be stored in the transaction log but not in any other file. In particular, it will not be persisted to the SST files. When iterating over this WriteBatch, WriteBatch::Handler::LogData will be called with the contents of the blob as it is encountered. Blobs, puts, deletes, and merges will be encountered in the same order in which they were inserted. The blob will NOT consume sequence number(s) and will NOT increase the count of the batch

      Example application: add timestamps to the transaction log for use in replication.

      Parameters:
      blob - binary object to be inserted
      Throws:
      RocksDBException - thrown if error happens in underlying native library.

    • clear

      void clear()
      Clear all updates buffered in this batch

    • setSavePoint

      void setSavePoint()
      Records the state of the batch for future calls to RollbackToSavePoint(). May be called multiple times to set multiple save points.

    • rollbackToSavePoint

      void rollbackToSavePoint() throws RocksDBException
      Remove all entries in this batch (Put, Merge, Delete, PutLogData) since the most recent call to SetSavePoint() and removes the most recent save point.
      Throws:
      RocksDBException - if there is no previous call to SetSavePoint()

    • popSavePoint

      void popSavePoint() throws RocksDBException
      Pop the most recent save point.

      That is to say that it removes the last save point, which was set by setSavePoint().

      Throws:
      RocksDBException - If there is no previous call to setSavePoint(), an exception with Status.Code.NotFound will be thrown.

    • setMaxBytes

      void setMaxBytes(long maxBytes)
      Set the maximum size of the write batch.
      Parameters:
      maxBytes - the maximum size in bytes.

    • getWriteBatch

      WriteBatch getWriteBatch()
      Get the underlying Write Batch.
      Returns:
      the underlying WriteBatch.