Overviewerlang logo

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:

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()}

Options used in commands.

Commands are put/5, 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:

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() | khepri_fun:standalone_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.

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 => khepri_fun:standalone_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() | khepri_fun:standalone_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.

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], 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() | khepri_fun:standalone_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() | khepri_fun:standalone_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.
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.
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.
delete_payload/1Deletes the payload of the tree node pointed to by the given path pattern.
delete_payload/2Deletes the payload of the tree node pointed to by the given path pattern.
delete_payload/3Deletes the payload of the tree node pointed to by the given path pattern.
delete_many_payloads/1Deletes the payload of all tree nodes matching the given path pattern.
delete_many_payloads/2Deletes the payload of all tree nodes matching the given path pattern.
delete_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.
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.
wait_for_async_ret/1Waits for an asynchronous call.
wait_for_async_ret/2Waits for an asynchronous call.
'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
'delete_payload!'/1
'delete_payload!'/2
'delete_payload!'/3
'delete_many_payloads!'/1
'delete_many_payloads!'/2
'delete_many_payloads!'/3
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.

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

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 wait_for_async_ret/1 function can be used to receive the message from Ra.

Example: 
%% Insert a tree node at `/:foo/:bar', overwriting the previous value.
ok = khepri_adv: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 wait_for_async_ret/1 function can be used to receive the message from Ra.

Example: 
%% Insert a tree node at `/:foo/:bar', overwriting the previous value.
ok = khepri_adv: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_adv: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_adv:delete_many(StoreId, [?KHEPRI_WILDCARD_STAR]).

See also: delete/3.

delete_payload/1

delete_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 delete_payload(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).

See also: delete_payload/2, delete_payload/3.

delete_payload/2

delete_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 delete_payload(StoreId, PathPattern, #{}).

See also: delete_payload/3.

delete_payload/3

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

delete_many_payloads/1

delete_many_payloads(PathPattern) -> Ret

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

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

See also: delete_many_payloads/2, delete_many_payloads/3.

delete_many_payloads/2

delete_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 delete_many_payloads(StoreId, PathPattern, #{}).

See also: delete_many_payloads/3.

delete_many_payloads/3

delete_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:delete_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.

transaction/1

transaction(Fun) -> Ret

Runs a transaction and returns its result.

Calling this function is the same as calling transaction(StoreId, Fun) with the default store ID.

See also: transaction/2.

transaction/2

transaction(StoreId, Fun) -> Ret

transaction(Fun, ReadWriteOrOptions) -> Ret

Runs a transaction and returns its result.

This function accepts the following two forms:

See also: transaction/3.

transaction/3

transaction(StoreId, Fun, ReadWrite) -> Ret

transaction(StoreId, Fun, Options) -> Ret

transaction(Fun, ReadWrite, Options) -> Ret

Runs a transaction and returns its result.

This function accepts the following three forms:

See also: transaction/4.

transaction/4

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

StoreId: the name of the Khepri store.
Fun: an arbitrary anonymous function.
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 Fun, 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 no arguments.

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

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

wait_for_async_ret/1

wait_for_async_ret(Correlation) -> Ret

Waits for an asynchronous call.

Calling this function is the same as calling wait_for_async_ret(Correlation) with the default timeout (see khepri_app:get_default_timeout/0).

See also: wait_for_async_ret/2.

wait_for_async_ret/2

wait_for_async_ret(Correlation, Timeout) -> Ret

Waits for an asynchronous call.

This function waits maximum Timeout milliseconds (or infinity) for the result of a previous call where the async option was set with a correlation ID. That correlation ID must be passed to this function.

See also: wait_for_async_ret/2.

'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

'delete_payload!'/1

'delete_payload!'(PathPattern) -> Payload

'delete_payload!'/2

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

'delete_payload!'/3

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

'delete_many_payloads!'/1

'delete_many_payloads!'(PathPattern) -> Payload

'delete_many_payloads!'/2

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

'delete_many_payloads!'/3

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

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.

Lists the content of specified store on stdout.

Overviewerlang logo

Generated by EDoc