WriteBatch

Overview

The WriteBatch class holds a collection of updates to apply atomically to a database. All updates are applied in the order they are added to the WriteBatch. WriteBatch supports Put, Delete, Merge, and DeleteRange operations.

Constructor

explicit WriteBatch(size_t reserved_bytes = 0, size_t max_bytes = 0)
explicit WriteBatch(size_t reserved_bytes, size_t max_bytes,
                    size_t protection_bytes_per_key, size_t default_cf_ts_sz)
explicit WriteBatch(const std::string& rep)
explicit WriteBatch(std::string&& rep)

size_t

default:"0"

Number of bytes to pre-allocate for the batch. Useful for avoiding reallocations when batch size is known.

size_t

default:"0"

Maximum size of the batch in bytes. If 0, no limit is enforced.

size_t

default:"0"

Number of bytes used to store protection information for each key entry. Currently supported values are zero (disabled) and eight.

Write Operations

Put

Store the mapping “key->value” in the database.

Status Put(ColumnFamilyHandle* column_family, const Slice& key, const Slice& value)
Status Put(const Slice& key, const Slice& value)
Status Put(ColumnFamilyHandle* column_family, const Slice& key,
           const Slice& ts, const Slice& value)
Status Put(ColumnFamilyHandle* column_family, const SliceParts& key,
           const SliceParts& value)

ColumnFamilyHandle*

Target column family. If nullptr, uses the default column family.

const Slice&

The key to store. When user-defined timestamp is enabled, key should point to a contiguous buffer with timestamp appended after user key.

const Slice&

User-defined timestamp for the key.

const Slice&

The value to associate with the key.

TimedPut (Experimental)

Stores the mapping “key->value” with a specified write time.

Status TimedPut(ColumnFamilyHandle* column_family, const Slice& key,
                const Slice& value, uint64_t write_unix_time)

uint64_t

Unix timestamp indicating when the write occurred.

PutEntity

Store wide column entities.

Status PutEntity(ColumnFamilyHandle* column_family, const Slice& key,
                 const WideColumns& columns)
Status PutEntity(const Slice& key, const AttributeGroups& attribute_groups)

Delete

Erase a key from the database.

Status Delete(ColumnFamilyHandle* column_family, const Slice& key)
Status Delete(const Slice& key)
Status Delete(ColumnFamilyHandle* column_family, const Slice& key, const Slice& ts)
Status Delete(ColumnFamilyHandle* column_family, const SliceParts& key)

SingleDelete

See DB::SingleDelete() for semantics and constraints.

Status SingleDelete(ColumnFamilyHandle* column_family, const Slice& key)
Status SingleDelete(const Slice& key)
Status SingleDelete(ColumnFamilyHandle* column_family, const Slice& key,
                    const Slice& ts)

DeleteRange

Delete a range of keys [begin_key, end_key).

Status DeleteRange(ColumnFamilyHandle* column_family,
                   const Slice& begin_key, const Slice& end_key)
Status DeleteRange(const Slice& begin_key, const Slice& end_key)
Status DeleteRange(ColumnFamilyHandle* column_family,
                   const Slice& begin_key, const Slice& end_key, const Slice& ts)

const Slice&

Start of the range (inclusive).

const Slice&

End of the range (exclusive).

Merge

Merge “value” with the existing value of “key” using the merge operator.

Status Merge(ColumnFamilyHandle* column_family,
             const Slice& key, const Slice& value)
Status Merge(const Slice& key, const Slice& value)

Utility Methods

Clear

void Clear()

Clear all updates buffered in this batch. Internally calls resize() on the string buffer, so allocated memory capacity may not be freed.

Count

uint32_t Count() const

Returns the number of updates in the batch.

GetDataSize

size_t GetDataSize() const

Returns the size of the serialized batch in bytes.

Data

const std::string& Data() const

Retrieve the serialized version of this batch.

SetMaxBytes

void SetMaxBytes(size_t max_bytes)

Set the maximum size limit for the batch.

Save Points

Save points allow you to rollback portions of a WriteBatch.

SetSavePoint

void SetSavePoint()

Records the state of the batch for future calls to RollbackToSavePoint(). May be called multiple times.

RollbackToSavePoint

Status RollbackToSavePoint()

Remove all entries added since the most recent SetSavePoint() and removes that save point. Returns Status::NotFound() if no save point exists.

PopSavePoint

Status PopSavePoint()

Pop the most recent save point without rolling back. Returns Status::NotFound() if no save point exists.

Content Queries

Query what types of operations are in the batch:

bool HasPut() const
bool HasTimedPut() const
bool HasPutEntity() const
bool HasDelete() const
bool HasSingleDelete() const
bool HasDeleteRange() const
bool HasMerge() const
bool HasBeginPrepare() const
bool HasEndPrepare() const
bool HasCommit() const
bool HasRollback() const

Iteration

Handler

Implement a WriteBatch::Handler to iterate over the contents of a batch:

class Handler {
 public:
  virtual Status PutCF(uint32_t column_family_id, const Slice& key,
                       const Slice& value);
  virtual Status DeleteCF(uint32_t column_family_id, const Slice& key);
  virtual Status SingleDeleteCF(uint32_t column_family_id, const Slice& key);
  virtual Status DeleteRangeCF(uint32_t column_family_id,
                               const Slice& begin_key, const Slice& end_key);
  virtual Status MergeCF(uint32_t column_family_id, const Slice& key,
                         const Slice& value);
  virtual void LogData(const Slice& blob);
  virtual bool Continue();
};

Iterate

Status Iterate(Handler* handler) const

Iterate over the batch contents, calling the appropriate handler methods.

Examples

// Atomically apply a set of updates
WriteBatch batch;
batch.Delete("key1");
batch.Put("key2", "value2");
batch.Put("key3", "value3");

Status s = db->Write(WriteOptions(), &batch);
assert(s.ok());

// The updates are applied in order
WriteBatch batch;
batch.Put("key", "v1");
batch.Delete("key");
batch.Put("key", "v2");
batch.Put("key", "v3");

db->Write(WriteOptions(), &batch);
// Final value of "key" will be "v3"

WriteBatch batch;
batch.Put("key1", "value1");
batch.SetSavePoint();

batch.Put("key2", "value2");
batch.Put("key3", "value3");

// Rollback key2 and key3
Status s = batch.RollbackToSavePoint();
assert(s.ok());

db->Write(WriteOptions(), &batch);
// Only key1 is written

ColumnFamilyHandle* cf1 = /* ... */;
ColumnFamilyHandle* cf2 = /* ... */;

WriteBatch batch;
batch.Put(cf1, "key1", "value1");
batch.Put(cf2, "key2", "value2");
batch.Delete(cf1, "key3");

db->Write(WriteOptions(), &batch);
// Updates applied atomically across column families

class MyHandler : public WriteBatch::Handler {
  Status PutCF(uint32_t cf_id, const Slice& key,
               const Slice& value) override {
    std::cout << "Put: " << key.ToString() << " = "
              << value.ToString() << std::endl;
    return Status::OK();
  }
  
  Status DeleteCF(uint32_t cf_id, const Slice& key) override {
    std::cout << "Delete: " << key.ToString() << std::endl;
    return Status::OK();
  }
};

WriteBatch batch;
batch.Put("key1", "value1");
batch.Delete("key2");

MyHandler handler;
batch.Iterate(&handler);

Thread Safety

Multiple threads can invoke const methods on a WriteBatch without external synchronization. However, if any thread may call a non-const method, all threads accessing the same WriteBatch must use external synchronization.

Database

Read & Write

Transactions

Storage

Utilities

Overview

Constructor

Write Operations

Put

TimedPut (Experimental)

PutEntity

Delete

SingleDelete

DeleteRange

Merge

Utility Methods

Clear

Count

GetDataSize

Data

SetMaxBytes

Save Points

SetSavePoint

RollbackToSavePoint

PopSavePoint

Content Queries

Iteration

Handler

Iterate

Examples

Thread Safety

See Also

​Overview

​Constructor

​Write Operations

​Put

​TimedPut (Experimental)

​PutEntity

​Delete

​SingleDelete

​DeleteRange

​Merge

​Utility Methods

​Clear

​Count

​GetDataSize

​Data

​SetMaxBytes

​Save Points

​SetSavePoint

​RollbackToSavePoint

​PopSavePoint

​Content Queries

​Iteration

​Handler

​Iterate

​Examples

​Thread Safety

​See Also

Overview

Constructor

Write Operations

Put

TimedPut (Experimental)

PutEntity

Delete

SingleDelete

DeleteRange

Merge

Utility Methods

Clear

Count

GetDataSize

Data

SetMaxBytes

Save Points

SetSavePoint

RollbackToSavePoint

PopSavePoint

Content Queries

Iteration

Handler

Iterate

Examples

Thread Safety

See Also