Module khepri

Khepri database API.

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

The API provides two ways to interact with a Khepri store: Simple operations are calls like: Transactions are like Mnesia ones. The caller passes an anonymous function to transaction/1, etc.:
khepri:transaction(
  fun() ->
      khepri_tx:put(Path, Value)
  end).
Simple operations are more efficient than transactions, but transactions are more flexible.

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.

Values are:

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.

See khepri:handle_async_ret/2.

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).

The child list version starts at 1 when a tree node is created. It is increased by 1 each time a child is added or removed. Changes made to existing nodes are not reflected in this version.

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.

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.

Values are:

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.

undefined is returned if a tree node has no payload attached to it.

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.

Default is the value to return if a tree node has no payload attached to it.

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.

By default, the payload (if any) and its version are returned by functions exposed by khepri_adv. The list of returned properties can be configured using the props_to_return option (see tree_options()).

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.

undefined is returned if a tree node has no payload attached to it.

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.

Default is the value to return if a tree node has no payload attached to it.

payload_version()

payload_version() = pos_integer()

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

The payload version starts at 1 when a tree node is created. It is increased by 1 each time the payload is added, modified or removed.

put_options()

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

Options specific to updates.

query_options()

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

Options used in queries.

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.

When reply_from is {member, Member} and the given member is not part of the cluster or when reply_from is local and there is no member local to the caller, the leader member will perform the reply. This mechanism uses the cluster membership information to decide which member should reply: if the given Member or local member is a member of the cluster but is offline or unreachable, no reply may be sent even though the leader may have successfully handled the command.

store_id()

store_id() = atom()

ID of a Khepri store.

This is the same as the Ra cluster name hosting the 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.

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

start/0Starts a store.
start/1Starts a store.
start/2Starts a store.
start/3Starts a store.
reset/0Resets the store on this Erlang node.
reset/1Resets the store on this Erlang node.
reset/2Resets the store on this Erlang node.
stop/0Stops a store.
stop/1Stops a store.
get_store_ids/0Returns the list of running stores.
is_empty/0Indicates if the store is empty or not.
is_empty/1Indicates if the store is empty or not.
is_empty/2Indicates if the store is empty or not.
get/1Returns the payload of the tree node pointed to by the given path pattern.
get/2Returns the payload of the tree node pointed to by the given path pattern.
get/3Returns the payload of the tree node pointed to by the given path pattern.
get_or/2Returns the payload of the tree node pointed to by the given path pattern, or a default value.
get_or/3Returns the payload of the tree node pointed to by the given path pattern, or a default value.
get_or/4Returns the payload of the tree node pointed to by the given path pattern, or a default value.
get_many/1Returns payloads of all the tree nodes matching the given path pattern.
get_many/2Returns payloads of all the tree nodes matching the given path pattern.
get_many/3Returns payloads of all the tree nodes matching the given path pattern.
get_many_or/2Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
get_many_or/3Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
get_many_or/4Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
exists/1Indicates if the tree node pointed to by the given path exists or not.
exists/2Indicates if the tree node pointed to by the given path exists or not.
exists/3Indicates if the tree node pointed to by the given path exists or not.
has_data/1Indicates if the tree node pointed to by the given path has data or not.
has_data/2Indicates if the tree node pointed to by the given path has data or not.
has_data/3Indicates if the tree node pointed to by the given path has data or not.
is_sproc/1Indicates if the tree node pointed to by the given path holds a stored procedure or not.
is_sproc/2Indicates if the tree node pointed to by the given path holds a stored procedure or not.
is_sproc/3Indicates if the tree node pointed to by the given path holds a stored procedure or not.
count/1Counts all tree nodes matching the given path pattern.
count/2Counts all tree nodes matching the given path pattern.
count/3Counts all tree nodes matching the given path pattern.
fold/3Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
fold/4Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
fold/5Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
foreach/2Calls Fun for each tree node matching the given path pattern.
foreach/3Calls Fun for each tree node matching the given path pattern.
foreach/4Calls Fun for each tree node matching the given path pattern.
map/2Produces a new map by calling Fun for each tree node matching the given path pattern.
map/3Produces a new map by calling Fun for each tree node matching the given path pattern.
map/4Produces a new map by calling Fun for each tree node matching the given path pattern.
filter/2Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
filter/3Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
filter/4Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
run_sproc/2Runs the stored procedure pointed to by the given path and returns the result.
run_sproc/3Runs the stored procedure pointed to by the given path and returns the result.
run_sproc/4Runs the stored procedure pointed to by the given path and returns the result.
put/2Sets the payload of the tree node pointed to by the given path pattern.
put/3Sets the payload of the tree node pointed to by the given path pattern.
put/4Sets the payload of the tree node pointed to by the given path pattern.
put_many/2Sets the payload of all the tree nodes matching the given path pattern.
put_many/3Sets the payload of all the tree nodes matching the given path pattern.
put_many/4Sets the payload of all the tree nodes matching the given path pattern.
create/2Creates a tree node with the given payload.
create/3Creates a tree node with the given payload.
create/4Creates a tree node with the given payload.
update/2Updates an existing tree node with the given payload.
update/3Updates an existing tree node with the given payload.
update/4Updates an existing tree node with the given payload.
compare_and_swap/3Updates an existing tree node with the given payload only if its data matches the given pattern.
compare_and_swap/4Updates an existing tree node with the given payload only if its data matches the given pattern.
compare_and_swap/5Updates an existing tree node with the given payload only if its data matches the given pattern.
delete/1Deletes the tree node pointed to by the given path pattern.
delete/2Deletes the tree node pointed to by the given path pattern.
delete/3Deletes the tree node pointed to by the given path pattern.
delete_many/1Deletes all tree nodes matching the given path pattern.
delete_many/2Deletes all tree nodes matching the given path pattern.
delete_many/3Deletes all tree nodes matching the given path pattern.
clear_payload/1Deletes the payload of the tree node pointed to by the given path pattern.
clear_payload/2Deletes the payload of the tree node pointed to by the given path pattern.
clear_payload/3Deletes the payload of the tree node pointed to by the given path pattern.
clear_many_payloads/1Deletes the payload of all tree nodes matching the given path pattern.
clear_many_payloads/2Deletes the payload of all tree nodes matching the given path pattern.
clear_many_payloads/3Deletes the payload of all tree nodes matching the given path pattern.
register_trigger/3Registers a trigger.
register_trigger/4Registers a trigger.
register_trigger/5Registers a trigger.
register_projection/2Registers a projection.
register_projection/3Registers a projection.
register_projection/4Registers a projection.
unregister_projection/1Removes a projection from the store by name.
unregister_projection/2Removes a projection from the store by name.
unregister_projection/3Removes a projection from the store by name.
transaction/1Runs a transaction and returns its result.
transaction/2Runs a transaction and returns its result.
transaction/3Runs a transaction and returns its result.
transaction/4Runs a transaction and returns its result.
transaction/5Runs a transaction and returns its result.
handle_async_ret/1Handles the Ra event sent for asynchronous call results.
handle_async_ret/2Handles the Ra event sent for asynchronous call results.
'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/2Exports a Khepri store using the Module callback module.
export/3Exports a Khepri store using the Module callback module.
export/4Exports a Khepri store using the Module callback module.
import/2Imports a previously exported set of tree nodes using the Module callback module.
import/3Imports a previously exported set of tree nodes using the Module callback module.
info/0Lists the running stores on stdout.
info/1Lists the content of specified store on stdout.
info/2Lists the content of specified store on stdout.

Function Details

start/0

start() -> Ret

Starts a store.

See also: khepri_cluster:start/0.

start/1

start(RaSystemOrDataDir::RaSystem | DataDir) -> Ret

Starts a store.

See also: khepri_cluster:start/1.

start/2

start(RaSystemOrDataDir::RaSystem | DataDir, StoreIdOrRaServerConfig::StoreId | RaServerConfig) -> Ret

Starts a store.

See also: khepri_cluster:start/2.

start/3

start(RaSystemOrDataDir::RaSystem | DataDir, StoreIdOrRaServerConfig::StoreId | RaServerConfig, Timeout) -> Ret

Starts a store.

See also: khepri_cluster:start/3.

reset/0

reset() -> Ret

Resets the store on this Erlang node.

See also: khepri_cluster:reset/0.

reset/1

reset(StoreIdOrTimeout::StoreId | Timeout) -> Ret

Resets the store on this Erlang node.

See also: khepri_cluster:reset/1.

reset/2

reset(StoreId, Timeout) -> Ret

Resets the store on this Erlang node.

See also: khepri_cluster:reset/2.

stop/0

stop() -> Ret

Stops a store.

See also: khepri_cluster:stop/0.

stop/1

stop(StoreId) -> Ret

Stops a store.

See also: khepri_cluster:stop/1.

get_store_ids/0

get_store_ids() -> [StoreId]

Returns the list of running stores.

See also: khepri_cluster:get_store_ids/0.

is_empty/0

is_empty() -> IsEmpty | Error

Indicates if the store is empty or not.

Calling this function is the same as calling is_empty(StoreId) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: is_empty/1, is_empty/2.

is_empty/1

is_empty(StoreId) -> IsEmpty | Error

is_empty(Options) -> IsEmpty | Error

Indicates if the store is empty or not.

This function accepts the following two forms:

See also: is_empty/2.

is_empty/2

is_empty(StoreId, Options) -> IsEmpty | Error

StoreId: the name of the Khepri store.
Options: query options such as favor.

returns: true if the store is empty, false if it is not, or an {error, Reason} tuple.

Indicates if the store is empty or not.

get/1

get(PathPattern) -> Ret

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

Calling this function is the same as calling get(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: get/2, get/3.

get/2

get(StoreId, PathPattern) -> Ret

get(PathPattern, Options) -> Ret

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

This function accepts the following two forms:

See also: get/3.

get/3

get(StoreId, PathPattern, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree node to get.
Options: query options.

returns: an {ok, Payload | undefined} tuple or an {error, Reason} tuple.

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.

Example: query a tree node which holds the atom value
%% Query the tree node at `/:foo/:bar'.
{ok, value} = khepri:get(StoreId, [foo, bar]).
Example: query an existing tree node with no payload
%% Query the tree node at `/:no_payload'.
{ok, undefined} = khepri:get(StoreId, [no_payload]).
Example: query a non-existent tree node
%% 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

get_or(PathPattern, Default) -> Ret

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

Calling this function is the same as calling get_or(StoreId, PathPattern, Default) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: get_or/3, get_or/4.

get_or/3

get_or(StoreId, PathPattern, Default) -> Ret

get_or(PathPattern, Default, Options) -> Ret

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

This function accepts the following two forms:

See also: get_or/4.

get_or/4

get_or(StoreId, PathPattern, Default, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree node to get.
Default: the default value to return in case the tree node has no payload or does not exist.
Options: query options.

returns: an {ok, Payload | Default} tuple or an {error, Reason} tuple.

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.

Example: query a tree node which holds the atom value
%% Query the tree node at `/:foo/:bar'.
{ok, value} = khepri:get_or(StoreId, [foo, bar], default).
Example: query an existing tree node with no payload
%% Query the tree node at `/:no_payload'.
{ok, default} = khepri:get_or(StoreId, [no_payload], default).
Example: query a non-existent tree node
%% 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

get_many(PathPattern) -> Ret

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

Calling this function is the same as calling get_many(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: get_many/2, get_many/3.

get_many/2

get_many(StoreId, PathPattern) -> Ret

get_many(PathPattern, Options) -> Ret

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

This function accepts the following two forms:

See also: get_many/3.

get_many/3

get_many(StoreId, PathPattern, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree nodes to get.
Options: query options.

returns: an {ok, PayloadsMap} tuple or an {error, Reason} tuple.

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.

Example: query all nodes in the tree
%% 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

get_many_or(PathPattern, Default) -> Ret

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

Calling this function is the same as calling get_many_or(StoreId, PathPattern, Default) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: get_many_or/3, get_many_or/4.

get_many_or/3

get_many_or(StoreId, PathPattern, Default) -> Ret

get_many_or(PathPattern, Default, Options) -> Ret

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

This function accepts the following two forms:

See also: get_many_or/4.

get_many_or/4

get_many_or(StoreId, PathPattern, Default, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree nodes to get.
Default: the default value to set in PayloadsMap for tree nodes with no payload.
Options: query options.

returns: an {ok, PayloadsMap} tuple or an {error, Reason} tuple.

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.

Example: query all nodes in the tree
%% 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

exists(PathPattern) -> Exists | Error

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

Calling this function is the same as calling exists(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: exists/2, exists/3.

exists/2

exists(StoreId, PathPattern) -> Exists | Error

exists(PathPattern, Options) -> Exists | Error

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

This function accepts the following two forms:

See also: exists/3.

exists/3

exists(StoreId, PathPattern, Options) -> Exists | Error

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the nodes to check.
Options: query options such as favor.

returns: true if the tree node exists, false if it does not, or an {error, Reason} tuple.

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.

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: get/3.

has_data/1

has_data(PathPattern) -> HasData | Error

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

Calling this function is the same as calling has_data(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: has_data/2, has_data/3.

has_data/2

has_data(StoreId, PathPattern) -> HasData | Error

has_data(PathPattern, Options) -> HasData | Error

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

This function accepts the following two forms:

See also: has_data/3.

has_data/3

has_data(StoreId, PathPattern, Options) -> HasData | Error

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the nodes to check.
Options: query options such as favor.

returns: true if tree the node holds data, false if it does not exist, has no payload or holds a stored procedure, or an {error, Reason} tuple.

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.

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: get/3.

is_sproc/1

is_sproc(PathPattern) -> IsSproc | Error

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

Calling this function is the same as calling is_sproc(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: is_sproc/2, is_sproc/3.

is_sproc/2

is_sproc(StoreId, PathPattern) -> IsSproc | Error

is_sproc(PathPattern, Options) -> IsSproc | Error

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

This function accepts the following two forms:

See also: is_sproc/3.

is_sproc/3

is_sproc(StoreId, PathPattern, Options) -> IsSproc | Error

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the nodes to check.
Options: query options such as favor.

returns: true if the tree node holds a stored procedure, false if it does not exist, has no payload or holds data, or an {error, Reason} tuple.

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.

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: get/3.

count/1

count(PathPattern) -> Ret

Counts all tree nodes matching the given path pattern.

Calling this function is the same as calling count(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: count/2, count/3.

count/2

count(StoreId, PathPattern) -> Ret

count(PathPattern, Options) -> Ret

Counts all tree nodes matching the given path pattern.

This function accepts the following two forms:

See also: count/3.

count/3

count(StoreId, PathPattern, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the nodes to count.
Options: query options such as favor.

returns: an {ok, Count} tuple with the number of matching tree nodes, or an {error, Reason} tuple.

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.

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

fold/3

fold(PathPattern, Fun, Acc) -> Ret

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

Calling this function is the same as calling fold(StoreId, PathPattern, Fun, Acc) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: fold/4, fold/5.

fold/4

fold(StoreId, PathPattern, Fun, Acc) -> Ret

fold(PathPattern, Fun, Acc, Options) -> Ret

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

This function accepts the following two forms:

See also: fold/5.

fold/5

fold(StoreId, PathPattern, Fun, Acc, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree nodes to get.
Fun: the function to call for each matching tree node.
Acc: the Erlang term to pass to the first call to Fun.
Options: query options.

returns: an {ok, NewAcc} tuple or an {error, Reason} tuple.

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.

Like the function passed to maps:fold/3, Fun must accept the following arguments:
  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.

Example: list all nodes in the tree
%% 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

foreach(PathPattern, Fun) -> Ret

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

Calling this function is the same as calling foreach(StoreId, PathPattern, Fun) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: foreach/3, foreach/4.

foreach/3

foreach(StoreId, PathPattern, Fun) -> Ret

foreach(PathPattern, Fun, Options) -> Ret

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

This function accepts the following two forms:

See also: foreach/4.

foreach/4

foreach(StoreId, PathPattern, Fun, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree nodes to get.
Fun: the function to call for each matching tree node.
Options: query options.

returns: ok or an {error, Reason} tuple.

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.

Like the function passed to maps:foreach/2, Fun must accept the following arguments:
  1. the native path of the tree node being handled
  2. the tree node properties map
Example: print all nodes in the tree
%% 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

map(PathPattern, Fun) -> Ret

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

Calling this function is the same as calling map(StoreId, PathPattern, Fun) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: map/3, map/4.

map/3

map(StoreId, PathPattern, Fun) -> Ret

map(PathPattern, Fun, Options) -> Ret

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

This function accepts the following two forms:

See also: map/4.

map/4

map(StoreId, PathPattern, Fun, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree nodes to get.
Fun: the function to call for each matching tree node.
Options: query options.

returns: {ok, Map} or an {error, Reason} tuple.

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.

Like the function passed to maps:map/2, Fun must accept the following arguments:
  1. the native path of the tree node being handled
  2. the tree node properties map
Example: create a map of the form "native path => string path"
%% 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

filter(PathPattern, Pred) -> Ret

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

Calling this function is the same as calling filter(StoreId, PathPattern, Pred) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: filter/3, filter/4.

filter/3

filter(StoreId, PathPattern, Pred) -> Ret

filter(PathPattern, Pred, Options) -> Ret

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

This function accepts the following two forms:

See also: filter/4.

filter/4

filter(StoreId, PathPattern, Pred, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree nodes to get.
Pred: the function to call for each matching tree node.
Options: query options.

returns: {ok, Map} or an {error, Reason} tuple.

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.

Like the function passed to maps:filter/2, Pred must accept the following arguments:
  1. the native path of the tree node being handled
  2. the tree node properties filter
Example: only keep tree nodes under /:foo
%% 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

run_sproc(PathPattern, Args) -> Ret

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

Calling this function is the same as calling run_sproc(StoreId, PathPattern, Args) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: run_sproc/3, run_sproc/4.

run_sproc/3

run_sproc(StoreId, PathPattern, Args) -> Ret

run_sproc(PathPattern, Args, Options) -> Ret

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

This function accepts the following two forms:

See also: run_sproc/4.

run_sproc/4

run_sproc(StoreId, PathPattern, Args, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree node holding the stored procedure.
Args: the list of args to pass to the stored procedure; its length must be equal to the stored procedure arity.
Options: query options.

returns: the result of the stored procedure execution, or throws an exception if the tree node does not exist, does not hold a stored procedure or if there was an error.

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.

The length of the Args list must match the number of arguments expected by the stored procedure.

See also: is_sproc/3.

put/2

put(PathPattern, Data) -> Ret

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

Calling this function is the same as calling put(StoreId, PathPattern, Data) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: put/3, put/4.

put/3

put(StoreId, PathPattern, Data) -> Ret

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

Calling this function is the same as calling put(StoreId, PathPattern, Data, #{}).

See also: put/4.

put/4

put(StoreId, PathPattern, Data, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree node to create or modify.
Data: the Erlang term or function to store, or a khepri_payload:payload() structure.
Options: command options.

returns: in the case of a synchronous call, ok or an {error, Reason} tuple; in the case of an asynchronous call, always ok (the actual return value may be sent by a message if a correlation ID was specified).

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.

The payload must be one of the following form:

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.

Example:
%% 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

put_many(PathPattern, Data) -> Ret

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

Calling this function is the same as calling put_many(StoreId, PathPattern, Data) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: put_many/3, put_many/4.

put_many/3

put_many(StoreId, PathPattern, Data) -> Ret

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

Calling this function is the same as calling put_many(StoreId, PathPattern, Data, #{}).

See also: put_many/4.

put_many/4

put_many(StoreId, PathPattern, Data, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree node to create or modify.
Data: the Erlang term or function to store, or a khepri_payload:payload() structure.
Options: command options.

returns: in the case of a synchronous call, ok or an {error, Reason} tuple; in the case of an asynchronous call, always ok (the actual return value may be sent by a message if a correlation ID was specified).

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.

The payload must be one of the following form:

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.

Example:
%% 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

create(PathPattern, Data) -> Ret

Creates a tree node with the given payload.

Calling this function is the same as calling create(StoreId, PathPattern, Data) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: create/3, create/4.

create/3

create(StoreId, PathPattern, Data) -> Ret

Creates a tree node with the given payload.

Calling this function is the same as calling create(StoreId, PathPattern, Data, #{}).

See also: create/4.

create/4

create(StoreId, PathPattern, Data, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree node to create.
Data: the Erlang term or function to store, or a khepri_payload:payload() structure.
Options: command options.

returns: in the case of a synchronous call, ok or an {error, Reason} tuple; in the case of an asynchronous call, always ok (the actual return value may be sent by a message if a correlation ID was specified).

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.

Internally, the PathPattern is modified to include an #if_node_exists{exists = false} condition on its last component.

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

update/2

update(PathPattern, Data) -> Ret

Updates an existing tree node with the given payload.

Calling this function is the same as calling update(StoreId, PathPattern, Data) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: update/3, update/4.

update/3

update(StoreId, PathPattern, Data) -> Ret

Updates an existing tree node with the given payload.

Calling this function is the same as calling update(StoreId, PathPattern, Data, #{}).

See also: update/4.

update/4

update(StoreId, PathPattern, Data, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree node to modify.
Data: the Erlang term or function to store, or a khepri_payload:payload() structure.
Options: command options.

returns: in the case of a synchronous call, ok or an {error, Reason} tuple; in the case of an asynchronous call, always ok (the actual return value may be sent by a message if a correlation ID was specified).

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.

Internally, the PathPattern is modified to include an #if_node_exists{exists = true} condition on its last component.

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

compare_and_swap/3

compare_and_swap(PathPattern, DataPattern, Data) -> Ret

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

Calling this function is the same as calling compare_and_swap(StoreId, PathPattern, DataPattern, Data) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: compare_and_swap/4, compare_and_swap/5.

compare_and_swap/4

compare_and_swap(StoreId, PathPattern, DataPattern, Data) -> Ret

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

Calling this function is the same as calling compare_and_swap(StoreId, PathPattern, DataPattern, Data, #{}).

See also: compare_and_swap/5.

compare_and_swap/5

compare_and_swap(StoreId, PathPattern, DataPattern, Data, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree node to modify.
Data: the Erlang term or function to store, or a khepri_payload:payload() structure.
Options: command options.

returns: in the case of a synchronous call, ok or an {error, Reason} tuple; in the case of an asynchronous call, always ok (the actual return value may be sent by a message if a correlation ID was specified).

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.

Internally, the PathPattern is modified to include an #if_data_matches{pattern = DataPattern} condition on its last component.

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

delete/1

delete(PathPattern) -> Ret

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

Calling this function is the same as calling delete(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: delete/2, delete/3.

delete/2

delete(StoreId, PathPattern) -> Ret

delete(PathPattern, Options) -> Ret

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

This function accepts the following two forms:

See also: delete/3.

delete/3

delete(StoreId, PathPattern, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the node to delete.
Options: command options.

returns: in the case of a synchronous call, ok or an {error, Reason} tuple; in the case of an asynchronous call, always ok (the actual return value may be sent by a message if a correlation ID was specified).

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.

Example:
%% 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

delete_many(PathPattern) -> Ret

Deletes all tree nodes matching the given path pattern.

Calling this function is the same as calling delete_many(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: delete_many/2, delete_many/3.

delete_many/2

delete_many(StoreId, PathPattern) -> Ret

delete_many(PathPattern, Options) -> Ret

Deletes all tree nodes matching the given path pattern.

This function accepts the following two forms:

See also: delete_many/3.

delete_many/3

delete_many(StoreId, PathPattern, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the nodes to delete.
Options: command options.

returns: in the case of a synchronous call, ok or an {error, Reason} tuple; in the case of an asynchronous call, always ok (the actual return value may be sent by a message if a correlation ID was specified).

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.

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

See also: delete/3.

clear_payload/1

clear_payload(PathPattern) -> Ret

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

Calling this function is the same as calling clear_payload(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: clear_payload/2, clear_payload/3.

clear_payload/2

clear_payload(StoreId, PathPattern) -> Ret

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

Calling this function is the same as calling clear_payload(StoreId, PathPattern, #{}).

See also: clear_payload/3.

clear_payload/3

clear_payload(StoreId, PathPattern, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree node to modify.
Options: command options.

returns: in the case of a synchronous call, ok or an {error, Reason} tuple; in the case of an asynchronous call, always ok (the actual return value may be sent by a message if a correlation ID was specified).

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

In other words, the payload is set to khepri_payload:no_payload(). Otherwise, the behavior is that of put/4.

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

clear_many_payloads/1

clear_many_payloads(PathPattern) -> Ret

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

Calling this function is the same as calling clear_many_payloads(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: clear_many_payloads/2, clear_many_payloads/3.

clear_many_payloads/2

clear_many_payloads(StoreId, PathPattern) -> Ret

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

Calling this function is the same as calling clear_many_payloads(StoreId, PathPattern, #{}).

See also: clear_many_payloads/3.

clear_many_payloads/3

clear_many_payloads(StoreId, PathPattern, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the tree nodes to modify.
Options: command options.

returns: in the case of a synchronous call, ok or an {error, Reason} tuple; in the case of an asynchronous call, always ok (the actual return value may be sent by a message if a correlation ID was specified).

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

In other words, the payload is set to khepri_payload:no_payload(). Otherwise, the behavior is that of put/4.

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

register_trigger/3

register_trigger(TriggerId, EventFilter, StoredProcPath) -> Ret

Registers a trigger.

Calling this function is the same as calling register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: register_trigger/4.

register_trigger/4

register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath) -> Ret

register_trigger(TriggerId, EventFilter, StoredProcPath, Options) -> Ret

Registers a trigger.

This function accepts the following two forms:

See also: register_trigger/5.

register_trigger/5

register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath, Options) -> Ret

StoreId: the name of the Khepri store.
TriggerId: the name of the trigger.
EventFilter: the event filter used to associate an event with a stored procedure.
StoredProcPath: the path to the stored procedure to execute when the corresponding event occurs.

returns: ok if the trigger was registered, an {error, Reason} tuple otherwise.

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.

It is guaranteed to run at least once. It could be executed multiple times if the Ra leader changes, therefore the stored procedure must be idempotent.

register_projection/2

register_projection(PathPattern, Projection) -> Ret

Registers a projection.

Calling this function is the same as calling register_projection(StoreId, PathPattern, Projection) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: register_projection/3.

register_projection/3

register_projection(StoreId, PathPattern, Projection) -> Ret

register_projection(PathPattern, Projection, Options) -> Ret

Registers a projection.

This function accepts the following two forms:

See also: register_projection/4.

register_projection/4

register_projection(StoreId, PathPattern, Projection, Options) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the pattern of tree nodes which the projection should watch.
Projection: the projection resource, created with khepri_projection:new/3.
Options: command options for registering the projection.

returns: ok if the projection was registered, an {error, Reason} tuple otherwise.

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.

Registering a projection fills the projection's ETS table with records from any tree nodes which match the PathPattern and are already in the store.

unregister_projection/1

unregister_projection(ProjectionName) -> Ret

Removes a projection from the store by name.

Calling this function is the same as calling unregister_projection(StoreId, ProjectionName) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: unregister_projection/2.

unregister_projection/2

unregister_projection(StoreId, ProjectionName) -> Ret

unregister_projection(ProjectionName, Options) -> Ret

Removes a projection from the store by name.

This function accepts the following two forms:

See also: unregister_projection/3.

unregister_projection/3

unregister_projection(StoreId, ProjectionName, Options) -> Ret

StoreId: the name of the Khepri store.
ProjectionName: the name of the projection to unregister as passed to khepri_projection:new/3.
Options: command options for unregistering the projection.

returns: ok if the projection was unregistered, an {error, Reason} tuple otherwise.

Removes a projection from the store by name.

transaction/1

transaction(FunOrPath) -> Ret

Runs a transaction and returns its result.

Calling this function is the same as calling transaction(FunOrPath, []) with the default store ID.

See also: transaction/2.

transaction/2

transaction(StoreId, FunOrPath) -> Ret

transaction(FunOrPath, Args) -> Ret

transaction(FunOrPath, ReadWriteOrOptions) -> Ret

Runs a transaction and returns its result.

This function accepts the following two forms:

See also: transaction/3.

transaction/3

transaction(StoreId, FunOrPath, Args) -> Ret

transaction(StoreId, FunOrPath, ReadWriteOrOptions) -> Ret

transaction(FunOrPath, Args, ReadWriteOrOptions) -> Ret

transaction(FunOrPath, ReadWrite, Options) -> Ret

Runs a transaction and returns its result.

This function accepts the following two forms:

See also: transaction/4.

transaction/4

transaction(StoreId, FunOrPath, Args, ReadWrite) -> Ret

transaction(StoreId, FunOrPath, Args, Options) -> Ret

transaction(StoreId, FunOrPath, ReadWrite, Options) -> Ret

transaction(FunOrPath, Args, ReadWrite, Options) -> Ret

Runs a transaction and returns its result.

This function accepts the following three forms:

See also: transaction/5.

transaction/5

transaction(StoreId, FunOrPath, Args, ReadWrite, Options) -> Ret

StoreId: the name of the Khepri store.
FunOrPath: an arbitrary anonymous function or a path pattern pointing to a stored procedure.
Args: a list of arguments to pass to FunOrPath.
ReadWrite: the read/write or read-only nature of the transaction.
Options: command options such as the command type.

returns: in the case of a synchronous transaction, {ok, Result} where Result is the return value of FunOrPath, or {error, Reason} if the anonymous function was aborted; in the case of an asynchronous transaction, always ok (the actual return value may be sent by a message if a correlation ID was specified).

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:

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.

The result of FunOrPath can be any term. That result is returned in an {ok, Result} tuple if the transaction is synchronous. The result is sent by message if the transaction is asynchronous and a correlation ID was specified.

handle_async_ret/1

handle_async_ret(RaEvent) -> Ret

Handles the Ra event sent for asynchronous call results.

Calling this function is the same as calling handle_async_ret(StoreId, RaEvent) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: handle_async_ret/2.

handle_async_ret/2

handle_async_ret(StoreId, RaEvent) -> Ret

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.

Example:
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!'(PathPattern) -> Payload

'get!'/2

'get!'(StoreId, PathPattern) -> Payload

'get!'(PathPattern, Options) -> Payload

'get!'/3

'get!'(StoreId, PathPattern, Options) -> Payload

'get_or!'/2

'get_or!'(PathPattern, Default) -> Payload

'get_or!'/3

'get_or!'(StoreId, PathPattern, Default) -> Payload

'get_or!'(PathPattern, Default, Options) -> Payload

'get_or!'/4

'get_or!'(StoreId, PathPattern, Default, Options) -> Payload

'get_many!'/1

'get_many!'(PathPattern) -> Payload

'get_many!'/2

'get_many!'(StoreId, PathPattern) -> Payload

'get_many!'(PathPattern, Options) -> Payload

'get_many!'/3

'get_many!'(StoreId, PathPattern, Options) -> Payload

'get_many_or!'/2

'get_many_or!'(PathPattern, Default) -> Payload

'get_many_or!'/3

'get_many_or!'(StoreId, PathPattern, Default) -> Payload

'get_many_or!'(PathPattern, Default, Options) -> Payload

'get_many_or!'/4

'get_many_or!'(StoreId, PathPattern, Default, Options) -> Payload

'exists!'/1

'exists!'(PathPattern) -> Exists

'exists!'/2

'exists!'(StoreId, PathPattern) -> Exists

'exists!'(PathPattern, Options) -> Exists

'exists!'/3

'exists!'(StoreId, PathPattern, Options) -> Exists

'has_data!'/1

'has_data!'(PathPattern) -> HasData

'has_data!'/2

'has_data!'(StoreId, PathPattern) -> HasData

'has_data!'(PathPattern, Options) -> HasData

'has_data!'/3

'has_data!'(StoreId, PathPattern, Options) -> HasData

'is_sproc!'/1

'is_sproc!'(PathPattern) -> IsSproc

'is_sproc!'/2

'is_sproc!'(StoreId, PathPattern) -> IsSproc

'is_sproc!'(PathPattern, Options) -> IsSproc

'is_sproc!'/3

'is_sproc!'(StoreId, PathPattern, Options) -> IsSproc

'count!'/1

'count!'(PathPattern) -> Payload

'count!'/2

'count!'(StoreId, PathPattern) -> Payload

'count!'(PathPattern, Options) -> Payload

'count!'/3

'count!'(StoreId, PathPattern, Options) -> Payload

'put!'/2

'put!'(PathPattern, Data) -> Payload

'put!'/3

'put!'(StoreId, PathPattern, Data) -> Payload

'put!'/4

'put!'(StoreId, PathPattern, Data, Options) -> Ret

'put_many!'/2

'put_many!'(PathPattern, Data) -> Payload

'put_many!'/3

'put_many!'(StoreId, PathPattern, Data) -> Payload

'put_many!'/4

'put_many!'(StoreId, PathPattern, Data, Options) -> Ret

'create!'/2

'create!'(PathPattern, Data) -> Payload

'create!'/3

'create!'(StoreId, PathPattern, Data) -> Payload

'create!'/4

'create!'(StoreId, PathPattern, Data, Options) -> Ret

'update!'/2

'update!'(PathPattern, Data) -> Payload

'update!'/3

'update!'(StoreId, PathPattern, Data) -> Payload

'update!'/4

'update!'(StoreId, PathPattern, Data, Options) -> Ret

'compare_and_swap!'/3

'compare_and_swap!'(PathPattern, DataPattern, Data) -> Payload

'compare_and_swap!'/4

'compare_and_swap!'(StoreId, PathPattern, DataPattern, Data) -> Payload

'compare_and_swap!'/5

'compare_and_swap!'(StoreId, PathPattern, DataPattern, Data, Options) -> Ret

'delete!'/1

'delete!'(PathPattern) -> Payload

'delete!'/2

'delete!'(StoreId, PathPattern) -> Payload

'delete!'(PathPattern, Options) -> Ret

'delete!'/3

'delete!'(StoreId, PathPattern, Options) -> Ret

'delete_many!'/1

'delete_many!'(PathPattern) -> Payload

'delete_many!'/2

'delete_many!'(StoreId, PathPattern) -> Payload

'delete_many!'(PathPattern, Options) -> Ret

'delete_many!'/3

'delete_many!'(StoreId, PathPattern, Options) -> Ret

'clear_payload!'/1

'clear_payload!'(PathPattern) -> Payload

'clear_payload!'/2

'clear_payload!'(StoreId, PathPattern) -> Payload

'clear_payload!'/3

'clear_payload!'(StoreId, PathPattern, Options) -> Ret

'clear_many_payloads!'/1

'clear_many_payloads!'(PathPattern) -> Payload

'clear_many_payloads!'/2

'clear_many_payloads!'(StoreId, PathPattern) -> Payload

'clear_many_payloads!'/3

'clear_many_payloads!'(StoreId, PathPattern, Options) -> Ret

export/2

export(Module, ModulePriv) -> Ret

Exports a Khepri store using the Module callback module.

Calling this function is the same as calling export(StoreId, Module, ModulePriv) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: export/3, export/4.

export/3

export(StoreId::StoreId | PathPattern, Module, ModulePriv) -> Ret

Exports a Khepri store using the Module callback module.

This function accepts the following two forms:

See also: export/4.

export/4

export(StoreId, PathPattern, Module, ModulePriv) -> Ret

StoreId: the name of the Khepri store.
PathPattern: the path pattern matching the tree nodes to export.
Module: the callback module to use to export.
ModulePriv: arguments passed to Module:open_write/1.

returns: ok or an {ok, Term} tuple if the export succeeded (the actual return value depends on whether the callback module wants to return anything to the caller), or an {error, Reason} tuple if it failed.

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.

Example: export the full Khepri store using khepri_export_erlang as the callback module
ok = khepri:export(StoreId, khepri_export_erlang, "export-1.erl").
Example: export a subset of the Khepri store
ok = khepri:export(
       StoreId,
       "/:stock/:wood/**",
       khepri_export_erlang,
       "export-wood-stock-1.erl").

See also: import/3.

import/2

import(Module, ModulePriv) -> Ret

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

Calling this function is the same as calling import(StoreId, Module, ModulePriv) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: import/3.

import/3

import(StoreId, Module, ModulePriv) -> Ret

StoreId: the name of the Khepri store.
Module: the callback module to use to import.
ModulePriv: arguments passed to Module:open_read/1.

returns: ok or an {ok, Term} tuple if the import succeeded (the actual return value depends on whether the callback module wants to return anything to the caller), or an {error, Reason} tuple if it failed.

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.

Example: import a set of tree nodes using khepri_export_erlang as the callback module
ok = khepri:import(StoreId, khepri_export_erlang, "export-1.erl").

See also: export/3.

info/0

info() -> ok

Lists the running stores on stdout.

info/1

info(StoreId) -> ok

StoreId: the name of the Khepri store.

Lists the content of specified store on stdout.

info/2

info(StoreId, Options) -> ok

StoreId: the name of the Khepri store.
Options: query options.

Lists the content of specified store on stdout.


Generated by EDoc