Overview

Module khepri

• Description
• Data Types
• Function Index
• Function Details

Description

Khepri database API.

This module exposes the database API to manipulate data.

The API is mainly made of the functions used to perform simple direct atomic operations and queries on the database: get/1, put/2, delete/1 and so on. In addition to that, transaction/1 is the starting point to run transaction functions. However the API to use inside transaction functions is provided by khepri_tx.

Functions in this module have simplified return values to cover most frequent use cases. If you need more details about the queried or modified tree nodes, like the ability to distinguish a non-existent tree node from a tree node with no payload, you can use the khepri_adv module.

This module also provides functions to start and stop a simple unclustered Khepri store. For more advanced setup and clustering, see khepri_cluster.

A Khepri store

A Khepri store is one instance of Khepri running inside a Ra cluster (which could be made of a single Erlang node). It is possible to run multiple Khepri stores in parallel by creating multiple Ra clusters.

A Khepri store is started and configured with start/0, start/1 or start/3. To setup a cluster, see khepri_cluster.

When a store is started, a store ID store_id() is returned. This store ID is then used by the rest of this module's API. The returned store ID currently corresponds exactly to the Ra cluster name. It must be an atom though; other types are unsupported.

Interacting with the Khepri store

• Direct atomic function for simple operations
• Transactions for more complex operations

• Queries: get/1, exists/1, has_data/1, etc.
• Updates: put/2, delete/1, etc.

khepri:transaction(
  fun() ->
      khepri_tx:put(Path, Value)
  end).

Data Types

async_option()

async_option() = boolean() | ra_server:command_correlation() | ra_server:command_priority() | {ra_server:command_correlation(), ra_server:command_priority()}

Option to indicate if the command should be synchronous or asynchronous.

• true to perform an asynchronous low-priority command without a correlation ID.
• false to perform a synchronous command.
• A correlation ID to perform an asynchronous low-priority command with that correlation ID.
• A priority to perform an asynchronous command with the specified priority but without a correlation ID.
• A combination of a correlation ID and a priority to perform an asynchronous command with the specified parameters.

async_ret()

async_ret() = khepri_adv:single_result() | khepri_adv:many_results() | khepri_tx:tx_fun_result() | khepri:error(not_leader)

The value returned from of a command function which was executed asynchronously.

When a caller includes a correlation ID (ra_server:command_correlation()) async_option() in their khepri:command_options() on a command function, the caller will receive a ra_event message. Handling the notification with khepri:handle_async_ret/2 will return a list of pairs of correlation IDs (ra_server:command_correlation()) and the return values of the commands which were applied, or {error, not_leader} if the commands could not be applied since they were sent to a non-leader member.

Note that when commands are successfully applied, the return values are in the khepri_adv formats - khepri_adv:single_result() or khepri_adv:many_results() - rather than khepri:minimal_ret(), even if the command was sent using a function from the khepri API such as khepri:put/4.

child_list_length()

child_list_length() = non_neg_integer()

Number of direct child nodes under a tree node.

child_list_version()

child_list_version() = pos_integer()

Number of changes made to the list of child nodes of a tree node (child nodes added or removed).

command_options()

command_options() = #{timeout => timeout(), async => async_option(), reply_from => reply_from_option()}

Options used in commands.

Commands are put/4, delete/3 and read-write transaction/4.

• timeout is passed to Ra command processing function.
• async indicates the synchronous or asynchronous nature of the command; see async_option().
• reply_from indicates which cluster member should reply to the command request; see reply_from_option().

data()

data() = any()

Data stored in a tree node's payload.

error()

error() = error(any())

The error tuple returned by a function after a failure.

error()

error(Type) = {error, Type}

Return value of a failed command or query.

favor_option()

favor_option() = consistency | compromise | low_latency

Option to indicate where to put the cursor between freshness of the returned data and low latency of queries.

• consistent means that a "consistent query" will be used in Ra. It will return the most up-to-date piece of data the cluster agreed on. Note that it could block and eventually time out if there is no quorum in the Ra cluster.
• compromise performs "leader queries" most of the time to reduce latency, but uses "consistent queries" every 10 seconds to verify that the cluster is healthy on a regular basis. It should be faster but may block and time out like consistent and still return slightly out-of-date data.
• low_latency means that "local queries" are used exclusively. They are the fastest and have the lowest latency. However, the returned data is whatever the local Ra server has. It could be out-of-date if it has troubles keeping up with the Ra cluster. The chance of blocking and timing out is very small.

filter_fun()

filter_fun() = fun((khepri_path:native_path(), khepri:node_props()) -> boolean())

Function passed to khepri:filter/4.

fold_acc()

fold_acc() = any()

Term passed to and returned by a fold_fun/0.

fold_fun()

fold_fun() = fun((khepri_path:native_path(), khepri:node_props(), khepri:fold_acc()) -> khepri:fold_acc())

Function passed to khepri:fold/5.

foreach_fun()

foreach_fun() = fun((khepri_path:native_path(), khepri:node_props()) -> any())

Function passed to khepri:foreach/4.

many_payloads_ret()

many_payloads_ret() = many_payloads_ret(undefined)

The return value of query functions in the khepri module that work on a many nodes.

many_payloads_ret()

many_payloads_ret(Default) = khepri:ok(#{khepri_path:path() => khepri:data() | horus:horus_fun() | Default}) | khepri:error()

The return value of query functions in the khepri module that work on many nodes.

map_fun()

map_fun() = fun((khepri_path:native_path(), khepri:node_props()) -> khepri:map_fun_ret())

Function passed to khepri:map/4.

map_fun_ret()

map_fun_ret() = any()

Value returned by khepri:map_fun/0.

minimal_ret()

minimal_ret() = ok | khepri:error()

The return value of update functions in the khepri module.

node_props()

node_props() = #{data => khepri:data(), has_data => boolean(), sproc => horus:horus_fun(), is_sproc => boolean(), payload_version => khepri:payload_version(), child_list_version => khepri:child_list_version(), child_list_length => khepri:child_list_length(), child_names => [khepri_path:node_id()]}

Structure used to return properties, payload and child nodes for a specific tree node.

The payload in data or sproc is only returned if the tree node carries something. If that key is missing from the returned properties map, it means the tree node has no payload.

ok()

ok(Type) = {ok, Type}

The result of a function after a successful call, wrapped in an "ok" tuple.

payload_ret()

payload_ret() = payload_ret(undefined)

The return value of query functions in the khepri module that work on a single tree node.

payload_ret()

payload_ret(Default) = khepri:ok(khepri:data() | horus:horus_fun() | Default) | khepri:error()

The return value of query functions in the khepri module that work on a single tree node.

payload_version()

payload_version() = pos_integer()

Number of changes made to the payload of a tree node.

put_options()

put_options() = #{keep_while => khepri_condition:keep_while()}

Options specific to updates.

• keep_while allows to define keep-while conditions on the created/updated tree node.

query_options()

query_options() = #{timeout => timeout(), favor => favor_option()}

Options used in queries.

• timeout is passed to Ra query processing function.
• favor indicates where to put the cursor between freshness of the returned data and low latency of queries; see favor_option().

reply_from_option()

reply_from_option() = leader | local | {member, ra:server_id()}

Options to indicate which member of the cluster should reply to a command request.

Note that commands are always handled by the leader. This option only controls which member of the cluster carries out the reply.

• leader: the cluster leader will reply. This is the default value.
• {member, Member}: the given cluster member will reply.
• local: a member of the cluster on the same Erlang node as the caller will perform the reply.

store_id()

store_id() = atom()

ID of a Khepri store.

tree_options()

tree_options() = #{expect_specific_node => boolean(), props_to_return => [payload_version | child_list_version | child_list_length | child_names | payload | has_payload | raw_payload], include_root_props => boolean()}

Options used during tree traversal.

• expect_specific_node indicates if the path is expected to point to a specific tree node or could match many nodes.
• props_to_return indicates the list of properties to include in the returned tree node properties map. The default is [payload, payload_version]. Note that payload and has_payload are a bit special: the actually returned properties will be data/sproc and has_data/is_sproc respectively. raw_payload is for internal use only.
• include_root_props indicates if root properties and payload should be returned as well.

trigger_id()

trigger_id() = atom()

An ID to identify a registered trigger.

unwrapped_many_payloads_ret()

unwrapped_many_payloads_ret() = unwrapped_many_payloads_ret(undefined)

unwrapped_many_payloads_ret()

unwrapped_many_payloads_ret(Default) = #{khepri_path:path() => khepri:data() | horus:horus_fun() | Default}

unwrapped_minimal_ret()

unwrapped_minimal_ret() = khepri:minimal_ret()

unwrapped_payload_ret()

unwrapped_payload_ret() = unwrapped_payload_ret(undefined)

unwrapped_payload_ret()

unwrapped_payload_ret(Default) = khepri:data() | horus:horus_fun() | Default

Function Index

Function Details

start/0

Starts a store.

See also: khepri_cluster:start/0.

start/1

Starts a store.

See also: khepri_cluster:start/1.

start/2

Starts a store.

See also: khepri_cluster:start/2.

start/3

Starts a store.

See also: khepri_cluster:start/3.

reset/0

Resets the store on this Erlang node.

See also: khepri_cluster:reset/0.

reset/1

Resets the store on this Erlang node.

See also: khepri_cluster:reset/1.

reset/2

Resets the store on this Erlang node.

See also: khepri_cluster:reset/2.

stop/0

Stops a store.

See also: khepri_cluster:stop/0.

stop/1

Stops a store.

See also: khepri_cluster:stop/1.

get_store_ids/0

Returns the list of running stores.

See also: khepri_cluster:get_store_ids/0.

is_empty/0

Indicates if the store is empty or not.

See also: is_empty/1, is_empty/2.

is_empty/1

Indicates if the store is empty or not.

• is_empty(StoreId). Calling it is the same as calling is_empty(StoreId, #{}).
• is_empty(Options). Calling it is the same as calling is_empty(StoreId, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: is_empty/2.

is_empty/2

Indicates if the store is empty or not.

get/1

Returns the payload of the tree node pointed to by the given path pattern.

See also: get/2, get/3.

get/2

Returns the payload of the tree node pointed to by the given path pattern.

• get(StoreId, PathPattern). Calling it is the same as calling get(StoreId, PathPattern, #{}).
• get(PathPattern, Options). Calling it is the same as calling get(StoreId, PathPattern, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: get/3.

get/3

Returns the payload of the tree node pointed to by the given path pattern.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

The PathPattern must target a specific tree node. In other words, updating many nodes with the same payload is denied. That fact is checked before the tree node is looked up: so if a condition in the path could potentially match several nodes, an exception is raised, even though only one tree node would match at the time.

The returned {ok, Payload} tuple contains the payload of the targeted tree node, or {ok, undefined} if the tree node had no payload.

%% Query the tree node at `/:foo/:bar'.
{ok, value} = khepri:get(StoreId, [foo, bar]).

%% Query the tree node at `/:no_payload'.
{ok, undefined} = khepri:get(StoreId, [no_payload]).

%% Query the tree node at `/:non_existent'.
{error, ?khepri_error(node_not_found, _)} = khepri:get(
                                              StoreId, [non_existent]).

See also: get_many/3, get_or/3, khepri_adv:get/3.

get_or/2

Returns the payload of the tree node pointed to by the given path pattern, or a default value.

See also: get_or/3, get_or/4.

get_or/3

Returns the payload of the tree node pointed to by the given path pattern, or a default value.

• get_or(StoreId, PathPattern, Default). Calling it is the same as calling get_or(StoreId, PathPattern, Default, #{}).
• get_or(PathPattern, Default, Options). Calling it is the same as calling get_or(StoreId, PathPattern, Default, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: get_or/4.

get_or/4

Returns the payload of the tree node pointed to by the given path pattern, or a default value.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

The PathPattern must target a specific tree node. In other words, updating many nodes with the same payload is denied. That fact is checked before the tree node is looked up: so if a condition in the path could potentially match several nodes, an exception is raised, even though only one tree node would match at the time.

The returned {ok, Payload} tuple contains the payload of the targeted tree node, or {ok, Default} if the tree node had no payload or was not found.

%% Query the tree node at `/:foo/:bar'.
{ok, value} = khepri:get_or(StoreId, [foo, bar], default).

%% Query the tree node at `/:no_payload'.
{ok, default} = khepri:get_or(StoreId, [no_payload], default).

%% Query the tree node at `/:non_existent'.
{ok, default} = khepri:get_or(StoreId, [non_existent], default).

See also: get/3, get_many_or/4, khepri_adv:get/3.

get_many/1

Returns payloads of all the tree nodes matching the given path pattern.

See also: get_many/2, get_many/3.

get_many/2

Returns payloads of all the tree nodes matching the given path pattern.

• get_many(StoreId, PathPattern). Calling it is the same as calling get_many(StoreId, PathPattern, #{}).
• get_many(PathPattern, Options). Calling it is the same as calling get_many(StoreId, PathPattern, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: get_many/3.

get_many/3

Returns payloads of all the tree nodes matching the given path pattern.

Calling this function is the same as calling get_many_or(StoreId, PathPattern, undefined, Options).

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

The returned {ok, PayloadsMap} tuple contains a map where keys correspond to the path to a tree node matching the path pattern. Each key then points to the payload of that matching tree node, or Default if the tree node had no payload.

%% Get all nodes in the tree. The tree is:
%% <root>
%% `-- foo
%%     `-- bar = value
{ok, #{[foo] := undefined,
       [foo, bar] := value}} = khepri:get_many(
                                 StoreId,
                                 [?KHEPRI_WILDCARD_STAR_STAR]).

See also: get/3, get_many_or/4, khepri_adv:get_many/3.

get_many_or/2

Returns payloads of all the tree nodes matching the given path pattern, or a default payload.

See also: get_many_or/3, get_many_or/4.

get_many_or/3

Returns payloads of all the tree nodes matching the given path pattern, or a default payload.

• get_many_or(StoreId, PathPattern, Default). Calling it is the same as calling get_many_or(StoreId, PathPattern, Default, #{}).
• get_many_or(PathPattern, Default, Options). Calling it is the same as calling get_many_or(StoreId, PathPattern, Default, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: get_many_or/4.

get_many_or/4

Returns payloads of all the tree nodes matching the given path pattern, or a default payload.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

The returned {ok, PayloadsMap} tuple contains a map where keys correspond to the path to a tree node matching the path pattern. Each key then points to the payload of that matching tree node, or Default if the tree node had no payload.

%% Get all nodes in the tree. The tree is:
%% <root>
%% `-- foo
%%     `-- bar = value
{ok, #{[foo] := default,
       [foo, bar] := value}} = khepri:get_many_or(
                                 StoreId,
                                 [?KHEPRI_WILDCARD_STAR_STAR],
                                 default).

See also: get_many/3, get_or/4, khepri_adv:get_many/3.

exists/1

Indicates if the tree node pointed to by the given path exists or not.

See also: exists/2, exists/3.

exists/2

Indicates if the tree node pointed to by the given path exists or not.

• exists(StoreId, PathPattern). Calling it is the same as calling exists(StoreId, PathPattern, #{}).
• exists(PathPattern, Options). Calling it is the same as calling exists(StoreId, PathPattern, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: exists/3.

exists/3

Indicates if the tree node pointed to by the given path exists or not.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

See also: get/3.

has_data/1

Indicates if the tree node pointed to by the given path has data or not.

See also: has_data/2, has_data/3.

has_data/2

Indicates if the tree node pointed to by the given path has data or not.

• has_data(StoreId, PathPattern). Calling it is the same as calling has_data(StoreId, PathPattern, #{}).
• has_data(PathPattern, Options). Calling it is the same as calling has_data(StoreId, PathPattern, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: has_data/3.

has_data/3

Indicates if the tree node pointed to by the given path has data or not.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

See also: get/3.

is_sproc/1

Indicates if the tree node pointed to by the given path holds a stored procedure or not.

See also: is_sproc/2, is_sproc/3.

is_sproc/2

Indicates if the tree node pointed to by the given path holds a stored procedure or not.

• is_sproc(StoreId, PathPattern). Calling it is the same as calling is_sproc(StoreId, PathPattern, #{}).
• is_sproc(PathPattern, Options). Calling it is the same as calling is_sproc(StoreId, PathPattern, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: is_sproc/3.

is_sproc/3

Indicates if the tree node pointed to by the given path holds a stored procedure or not.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

See also: get/3.

count/1

Counts all tree nodes matching the given path pattern.

See also: count/2, count/3.

count/2

Counts all tree nodes matching the given path pattern.

• count(StoreId, PathPattern). Calling it is the same as calling count(StoreId, PathPattern, #{}).
• count(PathPattern, Options). Calling it is the same as calling count(StoreId, PathPattern, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: count/3.

count/3

Counts all tree nodes matching the given path pattern.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

The root node is not included in the count.

%% Query the tree node at `/:foo/:bar'.
{ok, 3} = khepri:count(StoreId, [foo, ?KHEPRI_WILDCARD_STAR]).

fold/3

Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.

See also: fold/4, fold/5.

fold/4

Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.

• fold(StoreId, PathPattern, Fun, Acc). Calling it is the same as calling fold(StoreId, PathPattern, Fun, Acc, #{}).
• fold(PathPattern, Fun, Acc, Options). Calling it is the same as calling fold(StoreId, PathPattern, Fun, Acc, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: fold/5.

fold/5

Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

1. the native path of the tree node being handled
2. the tree node properties map
3. an Erlang term which is either Acc for the first matched tree node, or the return value of the previous call to Fun

The returned {ok, NewAcc} tuple contains the return value of the last call to Fun, or Acc if no tree nodes matched the given path pattern.

%% List all tree node paths in the tree. The tree is:
%% <root>
%% `-- foo
%%     `-- bar = value
{ok, [[foo], [foo, bar]]} = khepri:fold(
                              StoreId,
                              [?KHEPRI_WILDCARD_STAR_STAR],
                              fun(Path, _NodeProps, Acc) ->
                                  [Path | Acc]
                              end, []).

foreach/2

Calls Fun for each tree node matching the given path pattern.

See also: foreach/3, foreach/4.

foreach/3

Calls Fun for each tree node matching the given path pattern.

• foreach(StoreId, PathPattern, Fun). Calling it is the same as calling foreach(StoreId, PathPattern, Fun, #{}).
• foreach(PathPattern, Fun, Options). Calling it is the same as calling foreach(StoreId, PathPattern, Fun, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: foreach/4.

foreach/4

Calls Fun for each tree node matching the given path pattern.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

1. the native path of the tree node being handled
2. the tree node properties map

%% Print all tree node paths in the tree. The tree is:
%% <root>
%% `-- foo
%%     `-- bar = value
ok = khepri:foreach(
          StoreId,
          [?KHEPRI_WILDCARD_STAR_STAR],
          fun(Path, _NodeProps) ->
              io:format("Path ~0p~n", [Path])
          end).

map/2

Produces a new map by calling Fun for each tree node matching the given path pattern.

See also: map/3, map/4.

map/3

Produces a new map by calling Fun for each tree node matching the given path pattern.

• map(StoreId, PathPattern, Fun). Calling it is the same as calling map(StoreId, PathPattern, Fun, #{}).
• map(PathPattern, Fun, Options). Calling it is the same as calling map(StoreId, PathPattern, Fun, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: map/4.

map/4

Produces a new map by calling Fun for each tree node matching the given path pattern.

The produced map uses the tree node path as the key, like get_many/3 and the return value of Fun as the value.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

1. the native path of the tree node being handled
2. the tree node properties map

%% The tree is:
%% <root>
%% `-- foo
%%     `-- bar = value
{ok, #{[foo] => "/:foo",
       [foo, bar] => "/:foo/:bar"}} = khepri:map(
                                        StoreId,
                                        [?KHEPRI_WILDCARD_STAR_STAR],
                                        fun(Path, _NodeProps) ->
                                            khepri_path:to_string(Path)
                                        end).

filter/2

Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.

See also: filter/3, filter/4.

filter/3

Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.

• filter(StoreId, PathPattern, Pred). Calling it is the same as calling filter(StoreId, PathPattern, Pred, #{}).
• filter(PathPattern, Pred, Options). Calling it is the same as calling filter(StoreId, PathPattern, Pred, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: filter/4.

filter/4

Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.

The produced map only contains tree nodes for which Pred returned true. The map has the same form as the one returned by get_many/3 otherwise.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

1. the native path of the tree node being handled
2. the tree node properties filter

%% The tree is:
%% <root>
%% `-- foo
%%     `-- bar = value
{ok, #{[foo] => undefined,
       [foo, bar] => value}} = khepri:filter(
                                 StoreId,
                                 [?KHEPRI_WILDCARD_STAR_STAR],
                                 fun
                                   ([foo | _], _NodeProps) -> true;
                                   (_Path, _NodeProps)     -> false
                                 end).

run_sproc/2

Runs the stored procedure pointed to by the given path and returns the result.

See also: run_sproc/3, run_sproc/4.

run_sproc/3

Runs the stored procedure pointed to by the given path and returns the result.

• run_sproc(StoreId, PathPattern, Args). Calling it is the same as calling run_sproc(StoreId, PathPattern, Args, #{}).
• run_sproc(PathPattern, Args, Options). Calling it is the same as calling run_sproc(StoreId, PathPattern, Args, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: run_sproc/4.

run_sproc/4

Runs the stored procedure pointed to by the given path and returns the result.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

The PathPattern must target a specific tree node. In other words, updating many nodes with the same payload is denied. That fact is checked before the tree node is looked up: so if a condition in the path could potentially match several nodes, an exception is raised, even though only one tree node would match at the time.

See also: is_sproc/3.

put/2

Sets the payload of the tree node pointed to by the given path pattern.

See also: put/3, put/4.

put/3

Sets the payload of the tree node pointed to by the given path pattern.

See also: put/4.

put/4

Sets the payload of the tree node pointed to by the given path pattern.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

The PathPattern must target a specific tree node. In other words, updating many nodes with the same payload is denied. That fact is checked before the tree node is looked up: so if a condition in the path could potentially match several nodes, an exception is raised, even though only one tree node would match at the time.

When using a simple path (i.e. without conditions), if the targeted tree node does not exist, it is created using the given payload. If the targeted tree node exists, it is updated with the given payload and its payload version is increased by one. Missing parent nodes are created on the way.

When using a path pattern, the behavior is the same. However if a condition in the path pattern is not met, an error is returned and the tree structure is not modified.

• An explicit absence of payload (khepri_payload:no_payload()), using the marker returned by khepri_payload:none/0, meaning there will be no payload attached to the tree node and the existing payload will be discarded if any
• An anonymous function; it will be considered a stored procedure and will be wrapped in a khepri_payload:sproc() record
• Any other term; it will be wrapped in a khepri_payload:data() record

It is possible to wrap the payload in its internal structure explicitly using the khepri_payload module directly.

The Options map may specify command-level options; see khepri:command_options(), khepri:tree_options() and khepri:put_options().

When doing an asynchronous update, the handle_async_ret/2 function can be used to handle the message received from Ra.

%% Insert a tree node at `/:foo/:bar', overwriting the previous value.
ok = khepri:put(StoreId, [foo, bar], new_value).

See also: compare_and_swap/5, create/4, put_many/4, update/4, khepri_adv:put/4.

put_many/2

Sets the payload of all the tree nodes matching the given path pattern.

See also: put_many/3, put_many/4.

put_many/3

Sets the payload of all the tree nodes matching the given path pattern.

See also: put_many/4.

put_many/4

Sets the payload of all the tree nodes matching the given path pattern.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

When using a simple path (i.e. without conditions), if the targeted tree node does not exist, it is created using the given payload. If the targeted tree node exists, it is updated with the given payload and its payload version is increased by one. Missing parent nodes are created on the way.

When using a path pattern, the behavior is the same. However if a condition in the path pattern is not met, an error is returned and the tree structure is not modified.

• An explicit absence of payload (khepri_payload:no_payload()), using the marker returned by khepri_payload:none/0, meaning there will be no payload attached to the tree node and the existing payload will be discarded if any
• An anonymous function; it will be considered a stored procedure and will be wrapped in a khepri_payload:sproc() record
• Any other term; it will be wrapped in a khepri_payload:data() record

It is possible to wrap the payload in its internal structure explicitly using the khepri_payload module directly.

The Options map may specify command-level options; see khepri:command_options(), khepri:tree_options() and khepri:put_options().

When doing an asynchronous update, the handle_async_ret/2 function can be used to handle the message received from Ra.

%% Insert a tree node at `/:foo/:bar', overwriting the previous value.
ok = khepri:put(StoreId, [foo, bar], new_value).

See also: put/4, khepri_adv:put_many/4.

create/2

Creates a tree node with the given payload.

See also: create/3, create/4.

create/3

Creates a tree node with the given payload.

See also: create/4.

create/4

Creates a tree node with the given payload.

The behavior is the same as put/4 except that if the tree node already exists, an {error, ?khepri_error(mismatching_node, Info)} tuple is returned.

See also: compare_and_swap/5, put/4, update/4, khepri_adv:create/4.

update/2

Updates an existing tree node with the given payload.

See also: update/3, update/4.

update/3

Updates an existing tree node with the given payload.

See also: update/4.

update/4

Updates an existing tree node with the given payload.

The behavior is the same as put/4 except that if the tree node already exists, an {error, ?khepri_error(mismatching_node, Info)} tuple is returned.

See also: compare_and_swap/5, create/4, put/4, khepri_adv:update/4.

compare_and_swap/3

Updates an existing tree node with the given payload only if its data matches the given pattern.

See also: compare_and_swap/4, compare_and_swap/5.

compare_and_swap/4

Updates an existing tree node with the given payload only if its data matches the given pattern.

See also: compare_and_swap/5.

compare_and_swap/5

Updates an existing tree node with the given payload only if its data matches the given pattern.

The behavior is the same as put/4 except that if the tree node already exists, an {error, ?khepri_error(mismatching_node, Info)} tuple is returned.

See also: create/4, put/4, update/4, khepri_adv:compare_and_swap/5.

delete/1

Deletes the tree node pointed to by the given path pattern.

See also: delete/2, delete/3.

delete/2

Deletes the tree node pointed to by the given path pattern.

• delete(StoreId, PathPattern). Calling it is the same as calling delete(StoreId, PathPattern, #{}).
• delete(PathPattern, Options). Calling it is the same as calling delete(StoreId, PathPattern, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: delete/3.

delete/3

Deletes the tree node pointed to by the given path pattern.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

The PathPattern must target a specific tree node. In other words, updating many nodes with the same payload is denied. That fact is checked before the tree node is looked up: so if a condition in the path could potentially match several nodes, an exception is raised, even though only one tree node would match at the time. If you want to delete multiple nodes at once, use delete_many/3.

%% Delete the tree node at `/:foo/:bar'.
ok = khepri:delete(StoreId, [foo, bar]).

See also: delete_many/3, khepri_adv:delete/3.

delete_many/1

Deletes all tree nodes matching the given path pattern.

See also: delete_many/2, delete_many/3.

delete_many/2

Deletes all tree nodes matching the given path pattern.

• delete_many(StoreId, PathPattern). Calling it is the same as calling delete(StoreId, PathPattern, #{}).
• delete_many(PathPattern, Options). Calling it is the same as calling delete(StoreId, PathPattern, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: delete_many/3.

delete_many/3

Deletes all tree nodes matching the given path pattern.

The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

%% Delete all nodes in the tree.
ok = khepri:delete_many(StoreId, [?KHEPRI_WILDCARD_STAR]).

See also: delete/3.

clear_payload/1

Deletes the payload of the tree node pointed to by the given path pattern.

See also: clear_payload/2, clear_payload/3.

clear_payload/2

Deletes the payload of the tree node pointed to by the given path pattern.

See also: clear_payload/3.

clear_payload/3

Deletes the payload of the tree node pointed to by the given path pattern.

See also: put/4, khepri_adv:clear_payload/3.

clear_many_payloads/1

Deletes the payload of all tree nodes matching the given path pattern.

See also: clear_many_payloads/2, clear_many_payloads/3.

clear_many_payloads/2

Deletes the payload of all tree nodes matching the given path pattern.

See also: clear_many_payloads/3.

clear_many_payloads/3

Deletes the payload of all tree nodes matching the given path pattern.

See also: delete_many/3, put/4, khepri_adv:clear_many_payloads/3.

register_trigger/3

Registers a trigger.

See also: register_trigger/4.

register_trigger/4

Registers a trigger.

• register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath). Calling it is the same as calling register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath, #{}).
• register_trigger(TriggerId, EventFilter, StoredProcPath, Options). Calling it is the same as calling register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: register_trigger/5.

register_trigger/5

Registers a trigger.

A trigger is based on an event filter. It associates an event with a stored procedure. When an event matching the event filter is emitted, the stored procedure is executed.

The following event filters are documented by khepri_evf:event_filter().

Here are examples of event filters:

%% An event filter can be explicitly created using the `khepri_evf'
%% module. This is possible to specify properties at the same time.
EventFilter = khepri_evf:tree([stock, wood, <<"oak">>], %% Required
                              #{on_actions => [delete], %% Optional
                                priority => 10}).       %% Optional

%% For ease of use, some terms can be automatically converted to an event
%% filter. In this example, a Unix-like path can be used as a tree event
%% filter.
EventFilter = "/:stock/:wood/oak".

The stored procedure is expected to accept a single argument. This argument is a map containing the event properties. Here is an example:

my_stored_procedure(Props) ->
    #{path := Path},
      on_action => Action} = Props.

The stored procedure is executed on the leader's Erlang node.

register_projection/2

Registers a projection.

See also: register_projection/3.

register_projection/3

Registers a projection.

• register_projection(StoreId, PathPattern, Projection). Calling it is the same as calling register_projection(StoreId, PathPattern, Projection, #{}).
• register_projection(PathPattern, Projection, Options). Calling it is the same as calling register_projection(StoreId, PathPattern, Projection, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: register_projection/4.

register_projection/4

Registers a projection.

A projection is a replicated ETS cache which is kept up to date by Khepri. See the khepri_projection module-docs for more information about projections.

This function associates a projection created with khepri_projection:new/3 with a pattern. Any changes to tree nodes matching the provided pattern will be turned into records using the projection's khepri_projection:projection_fun() and then applied to the projection's ETS table.

unregister_projection/1

Removes a projection from the store by name.

See also: unregister_projection/2.

unregister_projection/2

Removes a projection from the store by name.

• unregister_projection(StoreId, ProjectionName). Calling it is the same as calling unregister_projection(StoreId, ProjectionName, #{}).
• unregister_projection(ProjectionName, Options). Calling it is the same as calling unregister_projection(StoreId, ProjectionName, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: unregister_projection/3.

unregister_projection/3

Removes a projection from the store by name.

has_projection/1

Determines whether the store has a projection registered with the given name.

See also: has_projection/2.

has_projection/2

Determines whether the store has a projection registered with the given name.

• has_projection(StoreId, ProjectionName). Calling it is the same as calling has_projection(StoreId, ProjectionName, #{}).
• has_projection(ProjectionName, Options). Calling it is the same as calling has_projection(StoreId, ProjectionName, Options) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: has_projection/3.

has_projection/3

Determines whether the store has a projection registered with the given name.

transaction/1

Runs a transaction and returns its result.

See also: transaction/2.

transaction/2

Runs a transaction and returns its result.

• transaction(StoreId, FunOrPath). Calling it is the same as calling transaction(StoreId, FunOrPath, []).
• transaction(FunOrPath, Args). Calling it is the same as calling transaction(StoreId, FunOrPath, Args) with the default store ID.
• transaction(FunOrPath, ReadWriteOrOptions). Calling it is the same as calling transaction(StoreId, FunOrPath, [], ReadWriteOrOptions) with the default store ID.

See also: transaction/3.

transaction/3

Runs a transaction and returns its result.

• transaction(StoreId, FunOrPath, Args). Calling it is the same as calling transaction(StoreId, FunOrPath, Args, auto).
• transaction(StoreId, FunOrPath, ReadWriteOrOptions). Calling it is the same as calling transaction(StoreId, FunOrPath, [], ReadWriteOrOptions).
• transaction(FunOrPath, Args, ReadWriteOrOptions). Calling it is the same as calling transaction(StoreId, FunOrPath, Args, ReadWriteOrOptions) with the default store ID.

See also: transaction/4.

transaction/4

Runs a transaction and returns its result.

• transaction(StoreId, FunOrPath, Args, ReadWrite). Calling it is the same as calling transaction(StoreId, FunOrPath, Args, ReadWrite, #{}).
• transaction(StoreId, FunOrPath, Args, Options). Calling it is the same as calling transaction(StoreId, FunOrPath, Args, auto, Options).
• transaction(FunOrPath, Args, ReadWrite, Options). Calling it is the same as calling transaction(StoreId, FunOrPath, Args, ReadWrite, Options) with the default store ID.

See also: transaction/5.

transaction/5

Runs a transaction and returns its result.

Fun is an arbitrary anonymous function which takes the content of Args as its arguments. In other words, the length of Args must correspond to the arity of Fun.

Instead of Fun, PathPattern` can be passed. It must point to an existing stored procedure. The length to `Args must correspond to the arity of that stored procedure.

The ReadWrite flag determines what the Fun anonymous function is allowed to do and in which context it runs:

• If ReadWrite is ro, Fun can do whatever it wants, except modify the content of the store. In other words, uses of khepri_tx:put/2 or khepri_tx:delete/1 are forbidden and will abort the function. Fun is executed from a process on the leader Ra member.
• If ReadWrite is rw, Fun can use the khepri_tx transaction API as well as any calls to other modules as long as those functions or what they do is permitted. See khepri_tx for more details. If Fun does or calls something forbidden, the transaction will be aborted. Fun is executed in the context of the state machine process on each Ra members.
• If ReadWrite is auto, Fun is analyzed to determine if it calls khepri_tx:put/2 or khepri_tx:delete/1, or uses any denied operations for a read/write transaction. If it does, this is the same as setting ReadWrite to true. Otherwise, this is the equivalent of setting ReadWrite to false.

When using PathPattern, a ReadWrite of auto is synonymous of rw.

Options is relevant for both read-only and read-write transactions (including audetected ones). However note that both types expect different options.

handle_async_ret/1

Handles the Ra event sent for asynchronous call results.

See also: handle_async_ret/2.

handle_async_ret/2

Handles the Ra event sent for asynchronous call results.

When sending commands with async command_options(), the calling process will receive Ra events with the following structure:

{ra_event, CurrentLeader, {applied, [{Correlation1, Reply1}, ...]}}

or

{ra_event, FromId, {rejected, {not_leader, Leader | undefined, Correlation}}}

The first event acknowledges all commands handled in a batch while the second is sent per-command when commands are sent against a non-leader member.

These events should be passed to this function in order to map the return values from the async commands and to update leader information. This function does not handle retrying rejected commands or return values from applied commands - the caller is responsible for those tasks.

ok = khepri:put(StoreId, [stock, wood, <<"oak">>], 200, #{async => 1}),
ok = khepri:put(StoreId, [stock, wood, <<"maple">>], 150, #{async => 2}),
RaEvent = receive {ra_event, _, _} = Event -> Event end,
?assertMatch(
  [{1, {ok, #{[stock, wood, <<"oak">>] => _}}},
   {2, {ok, #{[stock, wood, <<"maple">>] => _}}}],
  khepri:handle_async_ret(RaEvent)).

See also: async_option(), ra:pipeline_command/4.

'get!'/1

'get!'/2

'get!'/3

'get_or!'/2

'get_or!'/3

'get_or!'/4

'get_many!'/1

'get_many!'/2

'get_many!'/3

'get_many_or!'/2

'get_many_or!'/3

'get_many_or!'/4

'exists!'/1

'exists!'/2

'exists!'/3

'has_data!'/1

'has_data!'/2

'has_data!'/3

'is_sproc!'/1

'is_sproc!'/2

'is_sproc!'/3

'count!'/1

'count!'/2

'count!'/3

'put!'/2

'put!'/3

'put!'/4

'put_many!'/2

'put_many!'/3

'put_many!'/4

'create!'/2

'create!'/3

'create!'/4

'update!'/2

'update!'/3

'update!'/4

'compare_and_swap!'/3

'compare_and_swap!'/4

'compare_and_swap!'/5

'delete!'/1

'delete!'/2

'delete!'/3

'delete_many!'/1

'delete_many!'/2

'delete_many!'/3

'clear_payload!'/1

'clear_payload!'/2

'clear_payload!'/3

'clear_many_payloads!'/1

'clear_many_payloads!'/2

'clear_many_payloads!'/3

export/2

Exports a Khepri store using the Module callback module.

See also: export/3, export/4.

export/3

Exports a Khepri store using the Module callback module.

• export(StoreId, Module, ModulePriv). Calling it is the same as calling export(StoreId, "**", Module, ModulePriv).
• export(PathPattern, Module, ModulePriv). Calling it is the same as calling export(StoreId, PathPattern, Module, ModulePriv) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: export/4.

export/4

Exports a Khepri store using the Module callback module.

The PathPattern allows to filter which tree nodes are exported. The path pattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.

Module is the callback module called to perform the actual export. It must conform to the Mnesia Backup & Restore API. See khepri_import_export for more details.

ModulePriv is the term passed to Module:open_write/1.

ok = khepri:export(StoreId, khepri_export_erlang, "export-1.erl").

ok = khepri:export(
       StoreId,
       "/:stock/:wood/**",
       khepri_export_erlang,
       "export-wood-stock-1.erl").

See also: import/3.

import/2

Imports a previously exported set of tree nodes using the Module callback module.

See also: import/3.

import/3

Imports a previously exported set of tree nodes using the Module callback module.

Module is the callback module called to perform the actual import. It must conform to the Mnesia Backup & Restore API. See khepri_import_export for more details.

ModulePriv is the term passed to Module:open_read/1.

Importing something doesn't delete existing tree nodes. The caller is responsible for deleting the existing content of a store if he needs to.

ok = khepri:import(StoreId, khepri_export_erlang, "export-1.erl").

See also: export/3.

info/0

Lists the running stores on stdout.

info/1

Lists the content of specified store on stdout.

info/2

Lists the content of specified store on stdout.

Overview

Generated by EDoc