# 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`