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. In addition to that, transaction/1 are the starting point to run transaction functions. However the API to use inside transaction functions is provided by khepri_tx.

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/0 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 node (child nodes added or removed).

The child list version starts at 1 when a 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 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:

node_props()

node_props() = #{data => data(), sproc => khepri_fun:standalone_fun(), payload_version => payload_version(), child_list_version => child_list_version(), child_list_length => child_list_length(), child_nodes => #{khepri_path:node_id() => node_props()}}

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

node_props_map()

node_props_map() = #{khepri_path:native_path() => node_props()}

Structure used to return a map of nodes and their associated properties, payload and child nodes.

This structure is used in the return value of all commands and queries.

ok()

ok(Type) = {ok, Type}

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

payload_version()

payload_version() = pos_integer()

Number of changes made to the payload of a node.

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

query_options()

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

Options used in queries.

result()

result() = khepri:ok(node_props_map()) | khepri:error()

Return value of a query or synchronous command.

store_id()

store_id() = atom()

ID of a Khepri store.

This is the same as the Ra cluster name hosting the Khepri store.

trigger_id()

trigger_id() = atom()

An ID to identify a registered trigger.

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.
put/2Creates or modifies a specific tree node in the tree structure.
put/3Creates or modifies a specific tree node in the tree structure.
put/4Creates or modifies a specific tree node in the tree structure.
put/5Creates or modifies a specific tree node in the tree structure.
create/2Creates a specific tree node in the tree structure only if it does not exist.
create/3Creates a specific tree node in the tree structure only if it does not exist.
create/4Creates a specific tree node in the tree structure only if it does not exist.
create/5Creates a specific tree node in the tree structure only if it does not exist.
update/2Updates a specific tree node in the tree structure only if it already exists.
update/3Updates a specific tree node in the tree structure only if it already exists.
update/4Updates a specific tree node in the tree structure only if it already exists.
update/5Updates a specific tree node in the tree structure only if it already exists.
compare_and_swap/3Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.
compare_and_swap/4Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.
compare_and_swap/5Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.
compare_and_swap/6Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.
clear_payload/1Clears the payload of a specific tree node in the tree structure.
clear_payload/2Clears the payload of a specific tree node in the tree structure.
clear_payload/3Clears the payload of a specific tree node in the tree structure.
clear_payload/4Clears the payload of a specific tree node in the tree structure.
delete/1Deletes all tree nodes matching the path pattern.
delete/2Deletes all tree nodes matching the path pattern.
delete/3Deletes all tree nodes matching the path pattern.
exists/1Returns true if the tree node pointed to by the given path exists, otherwise false.
exists/2Returns true if the tree node pointed to by the given path exists, otherwise false.
exists/3Returns true if the tree node pointed to by the given path exists, otherwise false.
get/1Returns all tree nodes matching the path pattern.
get/2Returns all tree nodes matching the path pattern.
get/3Returns all tree nodes matching the path pattern.
get_node_props/1Returns the tree node properties associated with the given node path.
get_node_props/2Returns the tree node properties associated with the given node path.
get_node_props/3Returns the tree node properties associated with the given node path.
has_data/1Returns true if the tree node pointed to by the given path has data, otherwise false.
has_data/2Returns true if the tree node pointed to by the given path has data, otherwise false.
has_data/3Returns true if the tree node pointed to by the given path has data, otherwise false.
get_data/1Returns the data associated with the given node path.
get_data/2Returns the data associated with the given node path.
get_data/3Returns the data associated with the given node path.
get_data_or/2Returns the data associated with the given node path, or Default if there is no data.
get_data_or/3Returns the data associated with the given node path, or Default if there is no data.
get_data_or/4Returns the data associated with the given node path, or Default if there is no data.
has_sproc/1Returns true if the tree node pointed to by the given path holds a stored procedure, otherwise false.
has_sproc/2Returns true if the tree node pointed to by the given path holds a stored procedure, otherwise false.
has_sproc/3Returns true if the tree node pointed to by the given path holds a stored procedure, otherwise false.
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.
count/1Counts all tree nodes matching the path pattern.
count/2Counts all tree nodes matching the path pattern.
count/3Counts all tree nodes matching the path pattern.
register_trigger/3Registers a trigger.
register_trigger/4Registers a trigger.
register_trigger/5Registers a trigger.
list/1Returns all direct child nodes under the given path.
list/2Returns all direct child nodes under the given path.
list/3Returns all direct child nodes under the given path.
find/2Returns all tree nodes matching the path pattern.
find/3Returns all tree nodes matching the path pattern.
find/4Finds tree nodes under PathPattern which match the given Condition.
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.
clear_store/0Wipes out the entire tree.
clear_store/1Wipes out the entire tree.
clear_store/2Wipes out the entire tree.
'put!'/2Creates or modifies a specific tree node in the tree structure.
'put!'/3Creates or modifies a specific tree node in the tree structure.
'put!'/4Creates or modifies a specific tree node in the tree structure.
'put!'/5Creates or modifies a specific tree node in the tree structure.
'create!'/2Creates a specific tree node in the tree structure only if it does not exist.
'create!'/3Creates a specific tree node in the tree structure only if it does not exist.
'create!'/4Creates a specific tree node in the tree structure only if it does not exist.
'create!'/5Creates a specific tree node in the tree structure only if it does not exist.
'update!'/2Updates a specific tree node in the tree structure only if it already exists.
'update!'/3Updates a specific tree node in the tree structure only if it already exists.
'update!'/4Updates a specific tree node in the tree structure only if it already exists.
'update!'/5Updates a specific tree node in the tree structure only if it already exists.
'compare_and_swap!'/3Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.
'compare_and_swap!'/4Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.
'compare_and_swap!'/5Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.
'compare_and_swap!'/6Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.
'get!'/1Returns all tree nodes matching the path pattern.
'get!'/2Returns all tree nodes matching the path pattern.
'get!'/3Returns all tree nodes matching the path pattern.
'delete!'/1Deletes all tree nodes matching the path pattern.
'delete!'/2Deletes all tree nodes matching the path pattern.
'delete!'/3Deletes all tree nodes matching the path pattern.
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.

put/2

put(PathPattern, Data) -> Result

Creates or modifies a specific tree node in the tree structure.

Calling this function is the same as calling put(StoreId, PathPattern, Data) with the default store ID.

See also: put/3.

put/3

put(StoreId, PathPattern, Data) -> Result

Creates or modifies a specific tree node in the tree structure.

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

See also: put/5.

put/4

put(StoreId, PathPattern, Data, Extra::Extra | Options) -> Result

Creates or modifies a specific tree node in the tree structure.

Calling this function is the same as calling put(StoreId, PathPattern, Data, Extra, Options) with an empty Extra or Options.

See also: put/5.

put/5

put(StoreId, PathPattern, Data, Extra, Options) -> Result

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the node to create or modify.
Data: the Erlang term or function to store, or a khepri_payload:payload() structure.
Extra: extra options such as keep_while conditions.
Options: command options such as the command type.

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

Creates or modifies a specific tree node in the tree structure.

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

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

When using a simple path (i.e. without conditions), if the target node does not exist, it is created using the given payload. If the target 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.

If the target node is modified, the returned structure in the "ok" tuple will have a single key corresponding to the resolved path of the target node. The path will be the same as the argument if it was a simple path, or the final path after conditions were applied if it was a path pattern. That key will point to a map containing the properties and payload (if any) of the node before the modification.

If the target node is created, the returned structure in the "ok" tuple will have a single key corresponding to the path of the target node. That key will point to an empty map, indicating there was no existing node (i.e. there was no properties or payload to return).

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 Extra map may specify put-specific options:

The Options map may specify command-level options; see command_options().

Example:
%% Insert a node at `/:foo/:bar', overwriting the previous value.
Result = khepri:put(StoreId, [foo, bar], new_value),
 
%% Here is the content of `Result'.
{ok, #{[foo, bar] => #{data => old_value,
                       payload_version => 1,
                       child_list_version => 1,
                       child_list_length => 0}}} = Result.

create/2

create(PathPattern, Data) -> Result

Creates a specific tree node in the tree structure only if it does not exist.

Calling this function is the same as calling create(StoreId, PathPattern, Data) with the default store ID.

See also: create/3.

create/3

create(StoreId, PathPattern, Data) -> Result

Creates a specific tree node in the tree structure only if it does not exist.

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

See also: create/5.

create/4

create(StoreId, PathPattern, Data, Extra::Extra | Options) -> Result

Creates a specific tree node in the tree structure only if it does not exist.

Calling this function is the same as calling create(StoreId, PathPattern, Data, Extra, Options) with an empty Extra or Options.

See also: create/5.

create/5

create(StoreId, PathPattern, Data, Extra, Options) -> Result

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the node to create or modify.
Data: the Erlang term or function to store, or a khepri_payload:payload() structure.
Extra: extra options such as keep_while conditions.
Options: command options such as the command type.

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

Creates a specific tree node in the tree structure only if it does not exist.

Internally, the PathPattern is modified to include an #if_node_exists{exists = false} condition on its last component. Otherwise, the behavior is that of put/5.

See also: put/5.

update/2

update(PathPattern, Data) -> Result

Updates a specific tree node in the tree structure only if it already exists.

Calling this function is the same as calling update(StoreId, PathPattern, Data) with the default store ID.

See also: update/3.

update/3

update(StoreId, PathPattern, Data) -> Result

Updates a specific tree node in the tree structure only if it already exists.

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

See also: update/5.

update/4

update(StoreId, PathPattern, Data, Extra::Extra | Options) -> Result

Updates a specific tree node in the tree structure only if it already exists.

Calling this function is the same as calling update(StoreId, PathPattern, Data, Extra, Options) with an empty Extra or Options.

See also: update/5.

update/5

update(StoreId, PathPattern, Data, Extra, Options) -> Result

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the node to create or modify.
Data: the Erlang term or function to store, or a khepri_payload:payload() structure.
Extra: extra options such as keep_while conditions.
Options: command options such as the command type.

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

Updates a specific tree node in the tree structure only if it already exists.

Internally, the PathPattern is modified to include an #if_node_exists{exists = true} condition on its last component. Otherwise, the behavior is that of put/5.

See also: put/5.

compare_and_swap/3

compare_and_swap(PathPattern, DataPattern, Data) -> Result

Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.

Calling this function is the same as calling compare_and_swap(StoreId, PathPattern, DataPattern, Data) with the default store ID.

See also: compare_and_swap/4.

compare_and_swap/4

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

Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.

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

See also: compare_and_swap/6.

compare_and_swap/5

compare_and_swap(StoreId, PathPattern, DataPattern, Data, Extra::Extra | Options) -> Result

Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.

Calling this function is the same as calling compare_and_swap(StoreId, PathPattern, DataPattern, Data, Extra, Options) with an empty Extra or Options.

See also: compare_and_swap/6.

compare_and_swap/6

compare_and_swap(StoreId, PathPattern, DataPattern, Data, Extra, Options) -> Result

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the node to create or modify.
Data: the Erlang term or function to store, or a khepri_payload:payload() structure.
Extra: extra options such as keep_while conditions.
Options: command options such as the command type.

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

Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.

Internally, the PathPattern is modified to include an #if_data_matches{pattern = DataPattern} condition on its last component. Otherwise, the behavior is that of put/5.

See also: put/5.

clear_payload/1

clear_payload(PathPattern) -> Result

Clears the payload of a specific tree node in the tree structure.

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

See also: clear_payload/2.

clear_payload/2

clear_payload(StoreId, PathPattern) -> Result

Clears the payload of a specific tree node in the tree structure.

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

See also: clear_payload/4.

clear_payload/3

clear_payload(StoreId, PathPattern, Extra::Extra | Options) -> Result

Clears the payload of a specific tree node in the tree structure.

Calling this function is the same as calling clear_payload(StoreId, PathPattern, Extra, Options) with an empty Extra or Options.

See also: clear_payload/4.

clear_payload/4

clear_payload(StoreId, PathPattern, Extra, Options) -> Result

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the node to create or modify.
Extra: extra options such as keep_while conditions.
Options: command options such as the command type.

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

Clears the payload of a specific tree node in the tree structure.

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

See also: put/5.

delete/1

delete(PathPattern) -> Result

Deletes all tree nodes matching the path pattern.

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

See also: delete/2.

delete/2

delete(StoreId, PathPattern) -> Result

delete(PathPattern, Options) -> Result

Deletes all tree nodes matching the path pattern.

This function accepts the following two forms:

See also: delete/3.

delete/3

delete(StoreId, PathPattern, Options) -> Result

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

returns: in the case of a synchronous delete, an {ok, Result} tuple with a map with zero, one or more entries, or an {error, Reason} tuple; in the case of an asynchronous put, always ok (the actual return value may be sent by a message if a correlation ID was specified).

Deletes all tree nodes matching the path pattern.

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

The returned structure in the "ok" tuple will have a key corresponding to the path for each deleted node. Each key will point to a map containing the properties and payload of that deleted node.

Example:
%% Delete the node at `/:foo/:bar'.
Result = khepri:delete(StoreId, [foo, bar]),
 
%% Here is the content of `Result'.
{ok, #{[foo, bar] => #{data => new_value,
                       payload_version => 2,
                       child_list_version => 1,
                       child_list_length => 0}}} = Result.

exists/1

exists(PathPattern) -> Exists

Returns true if the tree node pointed to by the given path exists, otherwise false.

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

See also: exists/2.

exists/2

exists(StoreId, PathPattern) -> Exists

exists(PathPattern, Options) -> Exists

Returns true if the tree node pointed to by the given path exists, otherwise false.

This function accepts the following two forms:

See also: exists/3.

exists/3

exists(StoreId, PathPattern, Options) -> Exists

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 exists, false if it does not exist or if there was any error.

Returns true if the tree node pointed to by the given path exists, otherwise false.

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

The PathPattern must point to a specific tree node and can't match multiple nodes.

See also: get/3.

get/1

get(PathPattern) -> Result

Returns all tree nodes matching the path pattern.

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

See also: get/2.

get/2

get(StoreId, PathPattern) -> Result

get(PathPattern, Options) -> Result

Returns all tree nodes matching the path pattern.

This function accepts the following two forms:

See also: get/3.

get/3

get(StoreId, PathPattern, Options) -> Result

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

returns: an {ok, Result} tuple with a map with zero, one or more entries, or an {error, Reason} tuple.

Returns all tree nodes matching the path pattern.

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

The returned structure in the "ok" tuple will have a key corresponding to the path for each node matching the path pattern. Each key will point to a map containing the properties and payload of that matching node.

The root node may or may not be included in the result. Currently, the root node is only included if the path pattern is one of the following: Example:
%% Query the node at `/:foo/:bar'.
Result = khepri:get(StoreId, [foo, bar]),
 
%% Here is the content of `Result'.
{ok, #{[foo, bar] => #{data => new_value,
                       payload_version => 2,
                       child_list_version => 1,
                       child_list_length => 0}}} = Result.

get_node_props/1

get_node_props(PathPattern) -> NodeProps

Returns the tree node properties associated with the given node path.

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

See also: get_node_props/2.

get_node_props/2

get_node_props(StoreId, PathPattern) -> NodeProps

get_node_props(PathPattern, Options) -> NodeProps

Returns the tree node properties associated with the given node path.

This function accepts the following two forms:

See also: get_node_props/3.

get_node_props/3

get_node_props(StoreId, PathPattern, Options) -> NodeProps

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: the tree node properties if the node exists, or throws an exception otherwise.

Returns the tree node properties associated with the given node path.

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

The PathPattern must point to a specific tree node and can't match multiple nodes.

Unlike get/3, this function is optimistic and returns the properties directly. If the node does not exist or if there are any errors, an exception is raised.

See also: get/3.

has_data/1

has_data(PathPattern) -> HasData

Returns true if the tree node pointed to by the given path has data, otherwise false.

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

See also: has_data/2.

has_data/2

has_data(StoreId, PathPattern) -> HasData

has_data(PathPattern, Options) -> HasData

Returns true if the tree node pointed to by the given path has data, otherwise false.

This function accepts the following two forms:

See also: has_data/3.

has_data/3

has_data(StoreId, PathPattern, Options) -> HasData

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, holds a stored procedure or if there was any error.

Returns true if the tree node pointed to by the given path has data, otherwise false.

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

The PathPattern must point to a specific tree node and can't match multiple nodes.

See also: get/3.

get_data/1

get_data(PathPattern) -> Data

Returns the data associated with the given node path.

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

See also: get_data/2.

get_data/2

get_data(StoreId, PathPattern) -> Data

get_data(PathPattern, Options) -> Data

Returns the data associated with the given node path.

This function accepts the following two forms:

See also: get_data/3.

get_data/3

get_data(StoreId, PathPattern, Options) -> Data

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: the data if the node has a data payload, or throws an exception if it does not exist, has no payload or holds a stored procedure.

Returns the data associated with the given node path.

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

The PathPattern must point to a specific tree node and can't match multiple nodes.

Unlike get/3, this function is optimistic and returns the data directly. An exception is raised for the following reasons:

See also: get/3.

get_data_or/2

get_data_or(PathPattern, Default) -> Data

Returns the data associated with the given node path, or Default if there is no data.

Calling this function is the same as calling get_data_or(StoreId, PathPattern, Default) with the default store ID.

See also: get_data_or/3.

get_data_or/3

get_data_or(StoreId, PathPattern, Default) -> Data

get_data_or(PathPattern, Default, Options) -> Data

Returns the data associated with the given node path, or Default if there is no data.

This function accepts the following two forms:

See also: get_data_or/4.

get_data_or/4

get_data_or(StoreId, PathPattern, Default, Options) -> Data

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the nodes to check.
Default: the default term to return if there is no data.
Options: query options such as favor.

returns: the data if the node has a data payload, or Default if it does not exist, has no payload or holds a stored procedure.

Returns the data associated with the given node path, or Default if there is no data.

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

The PathPattern must point to a specific tree node and can't match multiple nodes.

Default is returned if one of the following reasons is met:

See also: get/3.

has_sproc/1

has_sproc(PathPattern) -> HasStoredProc

Returns true if the tree node pointed to by the given path holds a stored procedure, otherwise false.

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

See also: has_sproc/2.

has_sproc/2

has_sproc(StoreId, PathPattern) -> HasStoredProc

has_sproc(PathPattern, Options) -> HasStoredProc

Returns true if the tree node pointed to by the given path holds a stored procedure, otherwise false.

This function accepts the following two forms:

See also: has_sproc/3.

has_sproc/3

has_sproc(StoreId, PathPattern, Options) -> HasStoredProc

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 node holds a stored procedure, false if it does not exist, has no payload, holds data or if there was any error.

Returns true if the tree node pointed to by the given path holds a stored procedure, otherwise false.

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

The PathPattern must point to a specific tree node and can't match multiple nodes.

See also: get/3.

run_sproc/2

run_sproc(PathPattern, Args) -> Result

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

run_sproc/3

run_sproc(StoreId, PathPattern, Args) -> Result

run_sproc(PathPattern, Args, Options) -> Result

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

run_sproc/4

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

StoreId: the name of the Khepri store.
PathPattern: the path (or path pattern) to the nodes to check.
Args: the list of args to pass to the stored procedure; its length must be equal to the stored procedure arity.
Options: query options such as favor.

returns: the result of the stored procedure execution, or throws an exception if the 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 native path (a list of node names and conditions) or as a string. See khepri_path:from_string/1.

The PathPattern must point to a specific tree node and can't match multiple nodes.

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

count/1

count(PathPattern) -> Result

Counts all tree nodes matching the path pattern.

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

See also: count/2.

count/2

count(StoreId, PathPattern) -> Result

count(PathPattern, Options) -> Result

Counts all tree nodes matching the path pattern.

This function accepts the following two forms:

See also: count/3.

count/3

count(StoreId, PathPattern, Options) -> Result

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 path pattern.

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

The root node is not included in the count.

It is implemented like get/3. Therefore, it is not faster. It will consume less memory though, as the result map is not constructed.

Example:
%% Query the node at `/:foo/:bar'.
Result = khepri:count(StoreId, [foo, ?STAR]),
 
%% Here is the content of `Result'.
{ok, 3} = Result.

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

list/1

list(PathPattern) -> Result

Returns all direct child nodes under the given path.

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

See also: list/2.

list/2

list(StoreId, PathPattern) -> Result

list(PathPattern, Options) -> Result

Returns all direct child nodes under the given path.

This function accepts the following two forms:

See also: list/3.

list/3

list(StoreId, PathPattern, Options) -> Result

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

returns: an {ok, Result} tuple with a map with zero, one or more entries, or an {error, Reason} tuple.

Returns all direct child nodes under the given path.

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

Internally, an #if_name_matches{regex = any} condition is appended to the PathPattern. Otherwise, the behavior is that of get/3.

See also: get/3.

find/2

find(PathPattern, Condition) -> Result

Returns all tree nodes matching the path pattern.

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

See also: find/3.

find/3

find(StoreId, PathPattern, Condition) -> Result

find(PathPattern, Condition, Options) -> Result

Returns all tree nodes matching the path pattern.

This function accepts the following two forms:

See also: find/4.

find/4

find(StoreId, PathPattern, Condition, Options) -> Result

StoreId: the name of the Khepri store.
PathPattern: the path indicating where to start the search from.
Condition: the condition nodes must match to be part of the result.

returns: an {ok, Result} tuple with a map with zero, one or more entries, or an {error, Reason} tuple.

Finds tree nodes under PathPattern which match the given Condition.

The PathPattern can be provided as a list of node names and conditions or as a string. See khepri_path:from_string/1.

Nodes are searched deeply under the given PathPattern, not only among direct child nodes.

Example:
%% Find nodes with data under `/:foo/:bar'.
Result = khepri:find(
           StoreId,
           [foo, bar],
           #if_has_data{has_data = true}),
 
%% Here is the content of `Result'.
{ok, #{[foo, bar, baz] => #{data => baz_value,
                            payload_version => 2,
                            child_list_version => 1,
                            child_list_length => 0},
       [foo, bar, deep, under, qux] => #{data => qux_value,
                                         payload_version => 1,
                                         child_list_version => 1,
                                         child_list_length => 0}}} = Result.

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, {atomic, Result} where Result is the return value of Fun, or {aborted, 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 {atomic, Result} tuple if the transaction is synchronous. The result is sent by message if the transaction is asynchronous and a correlation ID was specified.

clear_store/0

clear_store() -> Result

Wipes out the entire tree.

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

See also: clear_store/1.

clear_store/1

clear_store(StoreId) -> Result

clear_store(Options) -> Result

Wipes out the entire tree.

This function accepts the following two forms:

See also: clear_store/2.

clear_store/2

clear_store(StoreId, Options) -> Result

StoreId: the name of the Khepri store.
Options: command options such as the command type.

returns: in the case of a synchronous delete, an {ok, Result} tuple with a map with zero, one or more entries, or an {error, Reason} tuple; in the case of an asynchronous put, always ok (the actual return value may be sent by a message if a correlation ID was specified).

Wipes out the entire tree.

Note that the root node will remain unmodified however.

See also: delete/3.

'put!'/2

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

Creates or modifies a specific tree node in the tree structure.

Calling this function is the same as calling put/2 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: put/2.

'put!'/3

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

Creates or modifies a specific tree node in the tree structure.

Calling this function is the same as calling put/3 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: put/3.

'put!'/4

'put!'(StoreId, PathPattern, Data, ExtraOrOptions::Extra | Options) -> Result

Creates or modifies a specific tree node in the tree structure.

Calling this function is the same as calling put/4 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: put/4.

'put!'/5

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

Creates or modifies a specific tree node in the tree structure.

Calling this function is the same as calling put/5 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: put/5.

'create!'/2

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

Creates a specific tree node in the tree structure only if it does not exist.

Calling this function is the same as calling create/2 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: create/2.

'create!'/3

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

Creates a specific tree node in the tree structure only if it does not exist.

Calling this function is the same as calling create/3 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: create/3.

'create!'/4

'create!'(StoreId, PathPattern, Data, ExtraOrOptions::Extra | Options) -> Result

Creates a specific tree node in the tree structure only if it does not exist.

Calling this function is the same as calling create/4 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: create/4.

'create!'/5

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

Creates a specific tree node in the tree structure only if it does not exist.

Calling this function is the same as calling create/5 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: create/5.

'update!'/2

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

Updates a specific tree node in the tree structure only if it already exists.

Calling this function is the same as calling update/2 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: update/2.

'update!'/3

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

Updates a specific tree node in the tree structure only if it already exists.

Calling this function is the same as calling update/3 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: update/3.

'update!'/4

'update!'(StoreId, PathPattern, Data, ExtraOrOptions::Extra | Options) -> Result

Updates a specific tree node in the tree structure only if it already exists.

Calling this function is the same as calling update/4 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: update/4.

'update!'/5

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

Updates a specific tree node in the tree structure only if it already exists.

Calling this function is the same as calling update/5 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: update/5.

'compare_and_swap!'/3

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

Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.

Calling this function is the same as calling compare_and_swap/3 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: compare_and_swap/3.

'compare_and_swap!'/4

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

Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.

Calling this function is the same as calling compare_and_swap/4 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: compare_and_swap/4.

'compare_and_swap!'/5

'compare_and_swap!'(StoreId, PathPattern, DataPattern, Data, ExtraOrOptions::Extra | Options) -> Result

Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.

Calling this function is the same as calling compare_and_swap/5 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: compare_and_swap/5.

'compare_and_swap!'/6

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

Updates a specific tree node in the tree structure only if it already exists and its data matches the given DataPattern.

Calling this function is the same as calling compare_and_swap/6 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. If there is an error, an exception is thrown.

See also: compare_and_swap/6.

'get!'/1

'get!'(PathPattern) -> NodePropsMap

Returns all tree nodes matching the path pattern.

Calling this function is the same as calling get/1 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. It closer to Elixir conventions in pipelines however.

See also: get/1.

'get!'/2

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

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

Returns all tree nodes matching the path pattern.

Calling this function is the same as calling get/2 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. It closer to Elixir conventions in pipelines however.

See also: get/2.

'get!'/3

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

Returns all tree nodes matching the path pattern.

Calling this function is the same as calling get/3 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. It closer to Elixir conventions in pipelines however.

See also: get/3.

'delete!'/1

'delete!'(PathPattern) -> NodePropsMap

Deletes all tree nodes matching the path pattern.

Calling this function is the same as calling delete/1 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. It closer to Elixir conventions in pipelines however.

See also: delete/1.

'delete!'/2

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

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

Deletes all tree nodes matching the path pattern.

Calling this function is the same as calling delete/2 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. It closer to Elixir conventions in pipelines however.

See also: delete/2.

'delete!'/3

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

Deletes all tree nodes matching the path pattern.

Calling this function is the same as calling delete/3 but the result is unwrapped (from the {ok, Result} tuple) and returned directly. It closer to Elixir conventions in pipelines however.

See also: delete/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.

Lists the content of specified store on stdout.


Generated by EDoc