Hibari Client API Overview¶
As a key-value database, Hibari provides a simple client API with primitive operations for inserting, retrieving, and deleting data. Within certain restrictions, the API also supports compound operations that optionally can be executed as atomic transactions.
Supported Operations¶
Hibari’s client API supports the operations listed below.
Data Insertion¶
- brick_simple:add(Table, Key, Value[, ExpTime][, Flags][, Timeout])¶
Adds a key-value pair that does not yet exist, along with optional flags.
Successful adding of a new key-value pair:
> brick_simple:add(tab1, <<"foo">>, <<"Hello, world!">>).
{ok,1271542959131192}
Failed attempt to add a key that already exists:
> brick_simple:add(tab1, <<"foo">>, <<"Goodbye, world!">>).
{key_exists,1271542959131192}
- brick_simple:replace(Table, Key, Value[, ExpTime][, Flags][, Timeout])¶
Assigns a new value and/or new flags to a key that already exists.
- brick_simple:set(Table, Key, Value[, ExpTime][, Flags][, Timeout])¶
Sets a key-value pair and optional flags regardless of whether the key yet exists.
- brick_simple:rename(Table, Key, NewKey[, ExpTime][, Flags][, Timeout])¶
Renames a key that already exists.
Successful renaming of a key-value pair:
> brick_simple:rename(tab1, <<"my/foo">>, <<"my/bar">>).
{ok,1271543165272987}
rename operation fails if key and newkey do not share a common key prefix:
> brick_simple:rename(tab1, <<"my/foo">>, <<"her/foo">>).
...
See TODO (Creating New Table - VarPrefix) for more details.
Data Retrieval¶
- Retrieve a key and optionally its associated value and flags:
- link:#brick-simple-get[brick_simple:get/4]
- Retrieve multiple lexicographically contiguous keys and optionally
their associated values and flags:
- link:#brick-simple-get-many[brick_simple:get_many/5]
Data Deletion¶
- Delete a key-value pair and associated flags:
- link:#brick-simple-delete[brick_simple:delete/4]
Compound Operations¶
- Execute a specified list of operations, optionally as an atomic
transaction (micro-transaction):
- link:#brick-simple-do[brick_simple:do/4]
Fold Operations¶
- Implement a fold operation across all keys in a table:
- link:#brick-simple-fold-table[brick_simple:fold_table/7]
- Implement a fold operation across all keys having a specified
prefix:
- link:#brick-simple-fold-key[brick_simple:fold_key_prefix/9]
Note
Fold operations are performed at client side, not server side.
Check and Swap (CAS)¶
If desired, clients can apply a “check and swap” (or “test and set”) logic to data insertion, retrieval, and deletion operations so that the operation will be executed only if the target key has the exact timestamp specified in the request.
Micro-Transaction¶
TODO