Interfaces

Comparator

class rocksdb.interfaces.Comparator

A Comparator object provides a total order across slices that are used as keys in an sstable or a database. A Comparator implementation must be thread-safe since rocksdb may invoke its methods concurrently from multiple threads.

compare(a, b)

Three-way comparison.

Parameters:

• a (bytes) – First field to compare

• b (bytes) – Second field to compare

Returns:

• -1 if a < b

• 0 if a == b

• 1 if a > b

Return type:

int

name()

The name of the comparator. Used to check for comparator mismatches (i.e., a DB created with one comparator is accessed using a different comparator).

The client of this package should switch to a new name whenever the comparator implementation changes in a way that will cause the relative ordering of any two keys to change.

Names starting with “rocksdb.” are reserved and should not be used by any clients of this package.

Return type:

bytes

Merge Operator

Essentially, a MergeOperator specifies the SEMANTICS of a merge, which only client knows. It could be numeric addition, list append, string concatenation, edit data structure, whatever. The library, on the other hand, is concerned with the exercise of this interface, at the right time (during get, iteration, compaction…)

To use merge, the client needs to provide an object implementing one of the following interfaces:

• AssociativeMergeOperator - for most simple semantics (always take two values, and merge them into one value, which is then put back into rocksdb). numeric addition and string concatenation are examples.

• MergeOperator - the generic class for all the more complex operations. One method (FullMerge) to merge a Put/Delete value with a merge operand. Another method (PartialMerge) that merges two operands together. This is especially useful if your key values have a complex structure but you would still like to support client-specific incremental updates.

AssociativeMergeOperator is simpler to implement. MergeOperator is simply more powerful.

See this page for more details https://github.com/facebook/rocksdb/wiki/Merge-Operator

AssociativeMergeOperator

class rocksdb.interfaces.AssociativeMergeOperator

merge(key, existing_value, value)

Gives the client a way to express the read -> modify -> write semantics

Parameters:

• key (bytes) – The key that’s associated with this merge operation

• existing_value (bytes) – The current value in the db. None indicates the key does not exist before this op

• value (bytes) – The value to update/merge the existing_value with

Returns:

True and the new value on success. All values passed in will be client-specific values. So if this method returns false, it is because client specified bad data or there was internal corruption. The client should assume that this will be treated as an error by the library.

Return type:

(bool, bytes)

name()

The name of the MergeOperator. Used to check for MergeOperator mismatches. For example a DB created with one MergeOperator is accessed using a different MergeOperator.

Return type:

bytes

MergeOperator

class rocksdb.interfaces.MergeOperator

full_merge(key, existing_value, operand_list)

Gives the client a way to express the read -> modify -> write semantics

Parameters:

• key (bytes) – The key that’s associated with this merge operation. Client could multiplex the merge operator based on it if the key space is partitioned and different subspaces refer to different types of data which have different merge operation semantics

• existing_value (bytes) – The current value in the db. None indicates the key does not exist before this op

• operand_list (list of bytes) – The sequence of merge operations to apply.

Returns:

True and the new value on success. All values passed in will be client-specific values. So if this method returns false, it is because client specified bad data or there was internal corruption. The client should assume that this will be treated as an error by the library.

Return type:

(bool, bytes)

partial_merge(key, left_operand, right_operand)

This function performs merge(left_op, right_op) when both the operands are themselves merge operation types that you would have passed to a DB::Merge() call in the same order. For example DB::Merge(key,left_op), followed by DB::Merge(key,right_op)).

PartialMerge should combine them into a single merge operation that is returned together with True This new value should be constructed such that a call to DB::Merge(key, new_value) would yield the same result as a call to DB::Merge(key, left_op) followed by DB::Merge(key, right_op).

If it is impossible or infeasible to combine the two operations, return (False, None) The library will internally keep track of the operations, and apply them in the correct order once a base-value (a Put/Delete/End-of-Database) is seen.

Parameters:

• key (bytes) – the key that is associated with this merge operation.

• left_operand (bytes) – First operand to merge

• right_operand (bytes) – Second operand to merge

Return type:

(bool, bytes)

Note

Presently there is no way to differentiate between error/corruption and simply “return false”. For now, the client should simply return false in any case it cannot perform partial-merge, regardless of reason. If there is corruption in the data, handle it in the FullMerge() function, and return false there.

name()

The name of the MergeOperator. Used to check for MergeOperator mismatches. For example a DB created with one MergeOperator is accessed using a different MergeOperator.

Return type:

bytes

FilterPolicy

class rocksdb.interfaces.FilterPolicy

create_filter(keys)

Create a bytestring which can act as a filter for keys.

Parameters:

keys (list of bytes) – list of keys (potentially with duplicates) that are ordered according to the user supplied comparator.

Returns:

A filter that summarizes keys

Return type:

bytes

key_may_match(key, filter)

Check if the key is maybe in the filter.

Parameters:

• key (bytes) – Key for a single entry inside the database

• filter (bytes) – Contains the data returned by a preceding call to create_filter on this class

Returns:

This method must return True if the key was in the list of keys passed to create_filter(). This method may return True or False if the key was not on the list, but it should aim to return False with a high probability.

Return type:

bool

name()

Return the name of this policy. Note that if the filter encoding changes in an incompatible way, the name returned by this method must be changed. Otherwise, old incompatible filters may be passed to methods of this type.

Return type:

bytes

SliceTransform

class rocksdb.interfaces.SliceTransform

SliceTransform is currently used to implement the ‘prefix-API’ of rocksdb. https://github.com/facebook/rocksdb/wiki/Proposal-for-prefix-API

transform(src)

Parameters:

src (bytes) – Full key to extract the prefix from.

Returns:

A tuple of two interges (offset, size). Where the first integer is the offset within the src and the second the size of the prefix after the offset. Which means the prefix is generted by src[offset:offset+size]

Return type:

(int, int)

in_domain(src)

Decide if a prefix can be extraced from src. Only if this method returns True transform() will be called.

Parameters:

src (bytes) – Full key to check.

Return type:

bool

in_range(prefix)

Checks if prefix is a valid prefix

Parameters:

prefix (bytes) – Prefix to check.

Returns:

True if prefix is a valid prefix.

Return type:

bool

name()

Return the name of this transformation.

Return type:

bytes