khepri (khepri v0.6.0)
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
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
Interacting with the Khepri store
The API provides two ways to interact with a Khepri store:- Direct atomic function for simple operations
- Transactions for more complex operations
- Queries:
get/1,exists/1,has_data/1, etc. - Updates:
put/2,delete/1, etc.
transaction/1, etc.: khepri:transaction(
fun() ->
khepri_tx:put(Path, Value)
end).Link to this section Summary
Types
Option to indicate if the command should be synchronous or asynchronous.
Number of changes made to the list of child nodes of a tree node (child nodes added or removed).
Options used in commands.
Option to indicate where to put the cursor between freshness of the returned data and low latency of queries.
khepri:filter/4.fold_fun().khepri:fold/5.khepri:foreach/4.The return value of query functions in the khepri module that work on a many nodes.
The return value of query functions in the khepri module that work on many nodes.
khepri:map/4.khepri:map_fun().khepri module.Structure used to return properties, payload and child nodes for a specific tree node.
The return value of query functions in the khepri module that work on a single tree node.
The return value of query functions in the khepri module that work on a single tree node.
Number of changes made to the payload of a tree node.
Options specific to updates.
Options used in queries.
Options to indicate which member of the cluster should reply to a command request.
ID of a Khepri store.
Options used during tree traversal.
Functions
Deletes the payload of all tree nodes matching the given path pattern.
Deletes the payload of all tree nodes matching the given path pattern.
Deletes the payload of all tree nodes matching the given path pattern.
Deletes the payload of the tree node pointed to by the given path pattern.
Deletes the payload of the tree node pointed to by the given path pattern.
Deletes the payload of the tree node pointed to by the given path pattern.
Updates an existing tree node with the given payload only if its data matches the given pattern.
Updates an existing tree node with the given payload only if its data matches the given pattern.
Updates an existing tree node with the given payload only if its data matches the given pattern.
Counts all tree nodes matching the given path pattern.
Counts all tree nodes matching the given path pattern.
Counts all tree nodes matching the given path pattern.
Creates a tree node with the given payload.
Creates a tree node with the given payload.
Creates a tree node with the given payload.
Deletes the tree node pointed to by the given path pattern.
Deletes the tree node pointed to by the given path pattern.
Deletes the tree node pointed to by the given path pattern.
Deletes all tree nodes matching the given path pattern.
Deletes all tree nodes matching the given path pattern.
Deletes all tree nodes matching the given path pattern.
Indicates if the tree node pointed to by the given path exists or not.
Indicates if the tree node pointed to by the given path exists or not.
Indicates if the tree node pointed to by the given path exists or not.
Exports a Khepri store using the Module callback module.
Exports a Khepri store using the Module callback module.
Exports a Khepri store using the Module callback module.
Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
Calls Fun for each tree node matching the given path pattern.
Calls Fun for each tree node matching the given path pattern.
Calls Fun for each tree node matching the given path pattern.
Returns the payload of the tree node pointed to by the given path pattern.
Returns the payload of the tree node pointed to by the given path pattern.
Returns the payload of the tree node pointed to by the given path pattern.
Returns payloads of all the tree nodes matching the given path pattern.
Returns payloads of all the tree nodes matching the given path pattern.
Returns payloads of all the tree nodes matching the given path pattern.
Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
Returns the payload of the tree node pointed to by the given path pattern, or a default value.
Returns the payload of the tree node pointed to by the given path pattern, or a default value.
Returns the payload of the tree node pointed to by the given path pattern, or a default value.
See also: khepri_cluster:get_store_ids/0.
Indicates if the tree node pointed to by the given path has data or not.
Indicates if the tree node pointed to by the given path has data or not.
Indicates if the tree node pointed to by the given path has data or not.
Imports a previously exported set of tree nodes using the Module callback module.
Imports a previously exported set of tree nodes using the Module callback module.
Indicates if the tree node pointed to by the given path holds a stored procedure or not.
Indicates if the tree node pointed to by the given path holds a stored procedure or not.
Indicates if the tree node pointed to by the given path holds a stored procedure or not.
Produces a new map by calling Fun for each tree node matching the given path pattern.
Produces a new map by calling Fun for each tree node matching the given path pattern.
Produces a new map by calling Fun for each tree node matching the given path pattern.
Sets the payload of the tree node pointed to by the given path pattern.
Sets the payload of the tree node pointed to by the given path pattern.
Sets the payload of the tree node pointed to by the given path pattern.
Sets the payload of all the tree nodes matching the given path pattern.
Sets the payload of all the tree nodes matching the given path pattern.
Sets the payload of all the tree nodes matching the given path pattern.
Registers a projection.
Registers a projection.
Registers a projection.
Registers a trigger.
Registers a trigger.
Registers a trigger.
See also: khepri_cluster:reset/0.
See also: khepri_cluster:reset/1.
See also: khepri_cluster:reset/2.
Runs the stored procedure pointed to by the given path and returns the result.
Runs the stored procedure pointed to by the given path and returns the result.
Runs the stored procedure pointed to by the given path and returns the result.
See also: khepri_cluster:start/0.
See also: khepri_cluster:start/1.
See also: khepri_cluster:start/2.
See also: khepri_cluster:start/3.
See also: khepri_cluster:stop/0.
See also: khepri_cluster:stop/1.
Runs a transaction and returns its result.
Runs a transaction and returns its result.
Runs a transaction and returns its result.
Runs a transaction and returns its result.
Runs a transaction and returns its result.
Updates an existing tree node with the given payload.
Updates an existing tree node with the given payload.
Updates an existing tree node with the given payload.
Waits for an asynchronous call.
Waits for an asynchronous call.
Link to this section Types
async_option/0
-type 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:trueto perform an asynchronous low-priority command without a correlation ID.falseto perform a synchronous command.- A correlation ID to perform an asynchronous low-priority command with that correlation ID.
- A priority to perform an asynchronous command with the specified priority but without a correlation ID.
- A combination of a correlation ID and a priority to perform an asynchronous command with the specified parameters.
child_list_length/0
-type child_list_length() :: non_neg_integer().
child_list_version/0
-type 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/0
-type command_options() :: #{timeout => timeout(), async => async_option(), reply_from => reply_from_option()}.
Options used in commands.
Commands are put/4, delete/3 and read-write transaction/4.
timeoutis passed to Ra command processing function.asyncindicates the synchronous or asynchronous nature of the command; seeasync_option().reply_fromindicates which cluster member should reply to the command request; seereply_from_option().
data/0
-type data() :: any().
error/0
-type error() :: error(any()).
error/1
-type error(Type) :: {error, Type}.
favor_option/0
-type 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:consistentmeans that a "consistent query" will be used in Ra. It will return the most up-to-date piece of data the cluster agreed on. Note that it could block and eventually time out if there is no quorum in the Ra cluster.compromiseperforms "leader queries" most of the time to reduce latency, but uses "consistent queries" every 10 seconds to verify that the cluster is healthy on a regular basis. It should be faster but may block and time out likeconsistentand still return slightly out-of-date data.low_latencymeans that "local queries" are used exclusively. They are the fastest and have the lowest latency. However, the returned data is whatever the local Ra server has. It could be out-of-date if it has troubles keeping up with the Ra cluster. The chance of blocking and timing out is very small.
filter_fun/0
-type filter_fun() :: fun((khepri_path:native_path(), khepri:node_props()) -> boolean()).
khepri:filter/4.
fold_acc/0
-type fold_acc() :: any().
fold_fun().
fold_fun/0
-type fold_fun() :: fun((khepri_path:native_path(), khepri:node_props(), khepri:fold_acc()) -> khepri:fold_acc()).
khepri:fold/5.
foreach_fun/0
-type foreach_fun() :: fun((khepri_path:native_path(), khepri:node_props()) -> any()).
khepri:foreach/4.
many_payloads_ret/0
-type 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/1
-type 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.
map_fun/0
-type map_fun() :: fun((khepri_path:native_path(), khepri:node_props()) -> khepri:map_fun_ret()).
khepri:map/4.
map_fun_ret/0
-type map_fun_ret() :: any().
khepri:map_fun().
minimal_ret/0
-type minimal_ret() :: ok | khepri:error().
khepri module.
node_props/0
-type 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.
khepri_adv. The list of returned properties can be configured using the props_to_return option (see tree_options()).
ok/1
-type ok(Type) :: {ok, Type}.
payload_ret/0
-type 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/1
-type 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/0
-type 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/0
-type put_options() :: #{keep_while => khepri_condition:keep_while()}.
Options specific to updates.
keep_whileallows to define keep-while conditions on the created/updated tree node.
query_options/0
-type query_options() :: #{timeout => timeout(), favor => favor_option()}.
Options used in queries.
timeoutis passed to Ra query processing function.favorindicates where to put the cursor between freshness of the returned data and low latency of queries; seefavor_option().
reply_from_option/0
-type reply_from_option() :: leader | local | {member, ra:server_id()}.
Options to indicate which member of the cluster should reply to a command request.
Note that commands are always handled by the leader. This option only controls which member of the cluster carries out the reply.
leader: the cluster leader will reply. This is the default value.{member, Member}: the given cluster member will reply.local: a member of the cluster on the same Erlang node as the caller will perform the reply.
reply_from is {member, Member} and the given member is not part of the cluster or when reply_from is local and there is no member local to the caller, the leader member will perform the reply. This mechanism uses the cluster membership information to decide which member should reply: if the given Member or local member is a member of the cluster but is offline or unreachable, no reply may be sent even though the leader may have successfully handled the command.
store_id/0
-type store_id() :: atom().
ID of a Khepri store.
This is the same as the Ra cluster name hosting the Khepri store.tree_options/0
-type tree_options() ::
#{expect_specific_node => boolean(),
props_to_return =>
[payload_version | child_list_version | child_list_length | child_names | payload |
has_payload | raw_payload],
include_root_props => boolean()}.
Options used during tree traversal.
expect_specific_nodeindicates if the path is expected to point to a specific tree node or could match many nodes.props_to_returnindicates the list of properties to include in the returned tree node properties map. The default is[payload, payload_version]. Note thatpayloadandhas_payloadare a bit special: the actually returned properties will bedata/sprocandhas_data/is_sprocrespectively.raw_payloadis for internal use only.include_root_propsindicates if root properties and payload should be returned as well.
trigger_id/0
-type trigger_id() :: atom().
unwrapped_many_payloads_ret/0
-type unwrapped_many_payloads_ret() :: unwrapped_many_payloads_ret(undefined).
unwrapped_many_payloads_ret/1
-type unwrapped_many_payloads_ret(Default) :: #{khepri_path:path() => khepri:data() | khepri_fun:standalone_fun() | Default}.
unwrapped_minimal_ret/0
-type unwrapped_minimal_ret() :: khepri:minimal_ret().
unwrapped_payload_ret/0
-type unwrapped_payload_ret() :: unwrapped_payload_ret(undefined).
unwrapped_payload_ret/1
-type unwrapped_payload_ret(Default) :: khepri:data() | khepri_fun:standalone_fun() | Default.
Link to this section Functions
clear_many_payloads(PathPattern)
-spec clear_many_payloads(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret().
Deletes the payload of all tree nodes matching the given path pattern.
Calling this function is the same as callingclear_many_payloads(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).See also: clear_many_payloads/2, clear_many_payloads/3.
clear_many_payloads(StoreId, PathPattern)
-spec clear_many_payloads(StoreId, PathPattern) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret().
Deletes the payload of all tree nodes matching the given path pattern.
Calling this function is the same as callingclear_many_payloads(StoreId, PathPattern, #{}).See also: clear_many_payloads/3.
clear_many_payloads(StoreId, PathPattern, Options)
-spec clear_many_payloads(StoreId, PathPattern, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret() | khepri_machine:async_ret().
Deletes the payload of all tree nodes matching the given path pattern.
In other words, the payload is set tokhepri_payload:no_payload(). Otherwise, the behavior is that of put/4.See also: delete_many/3, put/4, khepri_adv:clear_many_payloads/3.
clear_many_payloads!(PathPattern)
-spec 'clear_many_payloads!'(PathPattern) -> Payload when PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_minimal_ret().
clear_many_payloads!(StoreId, PathPattern)
-spec 'clear_many_payloads!'(StoreId, PathPattern) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_minimal_ret().
clear_many_payloads!(StoreId, PathPattern, Options)
-spec 'clear_many_payloads!'(StoreId, PathPattern, Options) -> Ret when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
clear_payload(PathPattern)
-spec clear_payload(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret().
Deletes the payload of the tree node pointed to by the given path pattern.
Calling this function is the same as callingclear_payload(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).See also: clear_payload/2, clear_payload/3.
clear_payload(StoreId, PathPattern)
-spec clear_payload(StoreId, PathPattern) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret().
Deletes the payload of the tree node pointed to by the given path pattern.
Calling this function is the same as callingclear_payload(StoreId, PathPattern, #{}).See also: clear_payload/3.
clear_payload(StoreId, PathPattern, Options)
-spec clear_payload(StoreId, PathPattern, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret() | khepri_machine:async_ret().
Deletes the payload of the tree node pointed to by the given path pattern.
In other words, the payload is set tokhepri_payload:no_payload(). Otherwise, the behavior is that of put/4.See also: put/4, khepri_adv:clear_payload/3.
clear_payload!(PathPattern)
-spec 'clear_payload!'(PathPattern) -> Payload when PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_minimal_ret().
clear_payload!(StoreId, PathPattern)
-spec 'clear_payload!'(StoreId, PathPattern) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_minimal_ret().
clear_payload!(StoreId, PathPattern, Options)
-spec 'clear_payload!'(StoreId, PathPattern, Options) -> Ret when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
compare_and_swap(PathPattern, DataPattern, Data)
-spec compare_and_swap(PathPattern, DataPattern, Data) -> Ret when PathPattern :: khepri_path:pattern(), DataPattern :: ets:match_pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_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 callingcompare_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(StoreId, PathPattern, DataPattern, Data)
-spec compare_and_swap(StoreId, PathPattern, DataPattern, Data) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), DataPattern :: ets:match_pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_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 callingcompare_and_swap(StoreId, PathPattern, DataPattern, Data, #{}).See also: compare_and_swap/5.
compare_and_swap(StoreId, PathPattern, DataPattern, Data, Options)
-spec compare_and_swap(StoreId, PathPattern, DataPattern, Data, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), DataPattern :: ets:match_pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret() | khepri_machine:async_ret().
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.
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.
compare_and_swap!(PathPattern, DataPattern, Data)
-spec 'compare_and_swap!'(PathPattern, DataPattern, Data) -> Payload when PathPattern :: khepri_path:pattern(), DataPattern :: ets:match_pattern(), Data :: khepri_payload:payload() | data() | fun(), Payload :: khepri:unwrapped_minimal_ret().
compare_and_swap!(StoreId, PathPattern, DataPattern, Data)
-spec 'compare_and_swap!'(StoreId, PathPattern, DataPattern, Data) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), DataPattern :: ets:match_pattern(), Data :: khepri_payload:payload() | data() | fun(), Payload :: khepri:unwrapped_minimal_ret().
compare_and_swap!(StoreId, PathPattern, DataPattern, Data, Options)
-spec 'compare_and_swap!'(StoreId, PathPattern, DataPattern, Data, Options) -> Ret when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), DataPattern :: ets:match_pattern(), Data :: khepri_payload:payload() | data() | fun(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
count(PathPattern)
-spec count(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: ok(Count) | error(), Count :: non_neg_integer().
Counts all tree nodes matching the given path pattern.
Calling this function is the same as callingcount(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).
count(StoreId, PathPattern)
-spec count(StoreId, PathPattern) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Ret :: ok(Count) | error(), Count :: non_neg_integer(); (PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: ok(Count) | error(), Count :: non_neg_integer().
Counts all tree nodes matching the given path pattern.
This function accepts the following two forms:count(StoreId, PathPattern). Calling it is the same as callingcount(StoreId, PathPattern, #{}).count(PathPattern, Options). Calling it is the same as callingcount(StoreId, PathPattern, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: count/3.
count(StoreId, PathPattern, Options)
-spec count(StoreId, PathPattern, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: ok(Count) | error(), Count :: non_neg_integer().
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]).count!(PathPattern)
-spec 'count!'(PathPattern) -> Payload when PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_payload_ret().
count!(StoreId, PathPattern)
-spec 'count!'(StoreId, PathPattern) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_payload_ret(); (PathPattern, Options) -> Payload when PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), Payload :: khepri:unwrapped_payload_ret().
count!(StoreId, PathPattern, Options)
-spec 'count!'(StoreId, PathPattern, Options) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), Payload :: khepri:unwrapped_payload_ret().
create(PathPattern, Data)
-spec create(PathPattern, Data) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Creates a tree node with the given payload.
Calling this function is the same as callingcreate(StoreId, PathPattern, Data) with the default store ID (see khepri_cluster:get_default_store_id/0).
create(StoreId, PathPattern, Data)
-spec create(StoreId, PathPattern, Data) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Creates a tree node with the given payload.
Calling this function is the same as callingcreate(StoreId, PathPattern, Data, #{}).See also: create/4.
create(StoreId, PathPattern, Data, Options)
-spec create(StoreId, PathPattern, Data, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret() | khepri_machine:async_ret().
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.
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.
create!(PathPattern, Data)
-spec 'create!'(PathPattern, Data) -> Payload when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Payload :: khepri:unwrapped_minimal_ret().
create!(StoreId, PathPattern, Data)
-spec 'create!'(StoreId, PathPattern, Data) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Payload :: khepri:unwrapped_minimal_ret().
create!(StoreId, PathPattern, Data, Options)
-spec 'create!'(StoreId, PathPattern, Data, Options) -> Ret when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
delete(PathPattern)
-spec delete(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret().
Deletes the tree node pointed to by the given path pattern.
Calling this function is the same as callingdelete(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).
delete(StoreId, PathPattern)
-spec delete(StoreId, PathPattern) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret(); (PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:command_options() | khepri:tree_options(), Ret :: khepri:minimal_ret().
Deletes the tree node pointed to by the given path pattern.
This function accepts the following two forms:delete(StoreId, PathPattern). Calling it is the same as callingdelete(StoreId, PathPattern, #{}).delete(PathPattern, Options). Calling it is the same as callingdelete(StoreId, PathPattern, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: delete/3.
delete(StoreId, PathPattern, Options)
-spec delete(StoreId, PathPattern, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:command_options() | khepri:tree_options(), Ret :: khepri:minimal_ret() | khepri_machine:async_ret().
Deletes the tree node pointed to by the given path pattern.
The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.
The PathPattern must target a specific tree node. In other words, updating many nodes with the same payload is denied. That fact is checked before the tree node is looked up: so if a condition in the path could potentially match several nodes, an exception is raised, even though only one tree node would match at the time. If you want to delete multiple nodes at once, use delete_many/3.
%% Delete the tree node at `/:foo/:bar'.
ok = khepri_adv:delete(StoreId, [foo, bar]).See also: delete_many/3, khepri_adv:delete/3.
delete!(PathPattern)
-spec 'delete!'(PathPattern) -> Payload when PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_minimal_ret().
delete!(StoreId, PathPattern)
-spec 'delete!'(StoreId, PathPattern) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_minimal_ret(); (PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: command_options() | khepri:tree_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
delete!(StoreId, PathPattern, Options)
-spec 'delete!'(StoreId, PathPattern, Options) -> Ret when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Options :: command_options() | khepri:tree_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
delete_many(PathPattern)
-spec delete_many(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret().
Deletes all tree nodes matching the given path pattern.
Calling this function is the same as callingdelete_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(StoreId, PathPattern)
-spec delete_many(StoreId, PathPattern) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Ret :: khepri:minimal_ret(); (PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:command_options() | khepri:tree_options(), Ret :: khepri:minimal_ret().
Deletes all tree nodes matching the given path pattern.
This function accepts the following two forms:delete_many(StoreId, PathPattern). Calling it is the same as callingdelete(StoreId, PathPattern, #{}).delete_many(PathPattern, Options). Calling it is the same as callingdelete(StoreId, PathPattern, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: delete_many/3.
delete_many(StoreId, PathPattern, Options)
-spec delete_many(StoreId, PathPattern, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:command_options() | khepri:tree_options(), Ret :: khepri:minimal_ret() | khepri_machine:async_ret().
Deletes all tree nodes matching the given path pattern.
The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.
%% Delete all nodes in the tree.
ok = khepri_adv:delete_many(StoreId, [?KHEPRI_WILDCARD_STAR]).See also: delete/3.
delete_many!(PathPattern)
-spec 'delete_many!'(PathPattern) -> Payload when PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_minimal_ret().
delete_many!(StoreId, PathPattern)
-spec 'delete_many!'(StoreId, PathPattern) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_minimal_ret(); (PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: command_options() | khepri:tree_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
delete_many!(StoreId, PathPattern, Options)
-spec 'delete_many!'(StoreId, PathPattern, Options) -> Ret when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Options :: command_options() | khepri:tree_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
exists(PathPattern)
-spec exists(PathPattern) -> Exists | Error when PathPattern :: khepri_path:pattern(), Exists :: boolean(), Error :: khepri:error().
Indicates if the tree node pointed to by the given path exists or not.
Calling this function is the same as callingexists(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).
exists(StoreId, PathPattern)
-spec exists(StoreId, PathPattern) -> Exists | Error when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Exists :: boolean(), Error :: khepri:error(); (PathPattern, Options) -> Exists | Error when PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), Exists :: boolean(), Error :: khepri:error().
Indicates if the tree node pointed to by the given path exists or not.
This function accepts the following two forms:exists(StoreId, PathPattern). Calling it is the same as callingexists(StoreId, PathPattern, #{}).exists(PathPattern, Options). Calling it is the same as callingexists(StoreId, PathPattern, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: exists/3.
exists(StoreId, PathPattern, Options)
-spec exists(StoreId, PathPattern, Options) -> Exists | Error when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), Exists :: boolean(), Error :: khepri:error().
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.
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.
exists!(PathPattern)
-spec 'exists!'(PathPattern) -> Exists when PathPattern :: khepri_path:pattern(), Exists :: boolean().
exists!(StoreId, PathPattern)
-spec 'exists!'(StoreId, PathPattern) -> Exists when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Exists :: boolean(); (PathPattern, Options) -> Exists when PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), Exists :: boolean().
exists!(StoreId, PathPattern, Options)
-spec 'exists!'(StoreId, PathPattern, Options) -> Exists when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), Exists :: boolean().
export(Module, ModulePriv)
-spec export(Module, ModulePriv) -> Ret when Module :: module(), ModulePriv :: khepri_import_export:module_priv(), Ret :: ok | {ok, ModulePriv} | {error, any()}.
Exports a Khepri store using the Module callback module.
export(StoreId, Module, ModulePriv) with the default store ID (see khepri_cluster:get_default_store_id/0).
export(StoreId, Module, ModulePriv)
-spec export(StoreId | PathPattern, Module, ModulePriv) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Module :: module(), ModulePriv :: khepri_import_export:module_priv(), Ret :: ok | {ok, ModulePriv} | {error, any()}.
Exports a Khepri store using the Module callback module.
export(StoreId, Module, ModulePriv). Calling it is the same as callingexport(StoreId, "**", Module, ModulePriv).export(PathPattern, Module, ModulePriv). Calling it is the same as callingexport(StoreId, PathPattern, Module, ModulePriv)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: export/4.
export(StoreId, PathPattern, Module, ModulePriv)
-spec export(StoreId, PathPattern, Module, ModulePriv) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Module :: module(), ModulePriv :: khepri_import_export:module_priv(), Ret :: ok | {ok, ModulePriv} | {error, any()}.
Exports a Khepri store using the Module callback module.
The PathPattern allows to filter which tree nodes are exported. The path pattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.
Module is the callback module called to perform the actual export. It must conform to the Mnesia Backup & Restore API. See khepri_import_export for more details.
ModulePriv is the term passed to khepri_import_export:open_write/1.
khepri_export_erlang as the callback module ok = khepri:export(StoreId, khepri_export_erlang, "export-1.erl"). ok = khepri:export(
StoreId,
"/:stock/:wood/**",
khepri_export_erlang,
"export-wood-stock-1.erl").See also: import/3.
filter(PathPattern, Pred)
-spec filter(PathPattern, Pred) -> Ret when PathPattern :: khepri_path:pattern(), Pred :: khepri:filter_fun(), Ret :: khepri:many_payloads_ret().
Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
filter(StoreId, PathPattern, Pred) with the default store ID (see khepri_cluster:get_default_store_id/0).
filter(StoreId, PathPattern, Pred)
-spec filter(StoreId, PathPattern, Pred) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Pred :: khepri:filter_fun(), Ret :: khepri:many_payloads_ret(); (PathPattern, Pred, Options) -> Ret when PathPattern :: khepri_path:pattern(), Pred :: khepri:filter_fun(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:many_payloads_ret().
Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
filter(StoreId, PathPattern, Pred). Calling it is the same as callingfilter(StoreId, PathPattern, Pred, #{}).filter(PathPattern, Pred, Options). Calling it is the same as callingfilter(StoreId, PathPattern, Pred, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: filter/4.
filter(StoreId, PathPattern, Pred, Options)
-spec filter(StoreId, PathPattern, Pred, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Pred :: khepri:filter_fun(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:many_payloads_ret().
Returns a map for which predicate Pred holds true in tree nodes matching the given path pattern.
The produced map only contains tree nodes for which Pred returned true. The map has the same form as the one returned by get_many/3 otherwise.
The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.
maps:filter/2, Pred must accept the following arguments:- the native path of the tree node being handled
- the tree node properties filter
/:foo %% The tree is:
%% <root>
%% `-- foo
%% `-- bar = value
{ok, #{[foo] => undefined,
[foo, bar] => value}} = khepri:filter(
StoreId,
[?KHEPRI_WILDCARD_STAR_STAR],
fun
([foo | _], _NodeProps) -> true;
(_Path, _NodeProps) -> false
end).fold(PathPattern, Fun, Acc)
-spec fold(PathPattern, Fun, Acc) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:fold_fun(), Acc :: khepri:fold_acc(), Ret :: khepri:ok(NewAcc) | khepri:error(), NewAcc :: Acc.
Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
fold(StoreId, PathPattern, Fun, Acc) with the default store ID (see khepri_cluster:get_default_store_id/0).
fold(StoreId, PathPattern, Fun, Acc)
-spec fold(StoreId, PathPattern, Fun, Acc) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Fun :: khepri:fold_fun(), Acc :: khepri:fold_acc(), Ret :: khepri:ok(NewAcc) | khepri:error(), NewAcc :: Acc; (PathPattern, Fun, Acc, Options) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:fold_fun(), Acc :: khepri:fold_acc(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:ok(NewAcc) | khepri:error(), NewAcc :: Acc.
Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
fold(StoreId, PathPattern, Fun, Acc). Calling it is the same as callingfold(StoreId, PathPattern, Fun, Acc, #{}).fold(PathPattern, Fun, Acc, Options). Calling it is the same as callingfold(StoreId, PathPattern, Fun, Acc, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: fold/5.
fold(StoreId, PathPattern, Fun, Acc, Options)
-spec fold(StoreId, PathPattern, Fun, Acc, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Fun :: khepri:fold_fun(), Acc :: khepri:fold_acc(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:ok(NewAcc) | khepri:error(), NewAcc :: Acc.
Calls Fun on successive tree nodes matching the given path pattern, starting with Acc.
The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.
maps:fold/3, Fun must accept the following arguments:- the native path of the tree node being handled
- the tree node properties map
- an Erlang term which is either
Accfor the first matched tree node, or the return value of the previous call toFun
The returned {ok, NewAcc} tuple contains the return value of the last call to Fun, or Acc if no tree nodes matched the given path pattern.
%% List all tree node paths in the tree. The tree is:
%% <root>
%% `-- foo
%% `-- bar = value
{ok, [[foo], [foo, bar]]} = khepri:fold(
StoreId,
[?KHEPRI_WILDCARD_STAR_STAR],
fun(Path, _NodeProps, Acc) ->
[Path | Acc]
end, []).foreach(PathPattern, Fun)
-spec foreach(PathPattern, Fun) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:foreach_fun(), Ret :: ok | khepri:error().
Calls Fun for each tree node matching the given path pattern.
foreach(StoreId, PathPattern, Fun) with the default store ID (see khepri_cluster:get_default_store_id/0).
foreach(StoreId, PathPattern, Fun)
-spec foreach(StoreId, PathPattern, Fun) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Fun :: khepri:foreach_fun(), Ret :: ok | khepri:error(); (PathPattern, Fun, Options) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:foreach_fun(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: ok | khepri:error().
Calls Fun for each tree node matching the given path pattern.
foreach(StoreId, PathPattern, Fun). Calling it is the same as callingforeach(StoreId, PathPattern, Fun, #{}).foreach(PathPattern, Fun, Options). Calling it is the same as callingforeach(StoreId, PathPattern, Fun, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: foreach/4.
foreach(StoreId, PathPattern, Fun, Options)
-spec foreach(StoreId, PathPattern, Fun, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Fun :: khepri:foreach_fun(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: ok | khepri:error().
Calls Fun for each tree node matching the given path pattern.
The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.
maps:foreach/2, Fun must accept the following arguments:- the native path of the tree node being handled
- the tree node properties map
%% Print all tree node paths in the tree. The tree is:
%% <root>
%% `-- foo
%% `-- bar = value
ok = khepri:foreach(
StoreId,
[?KHEPRI_WILDCARD_STAR_STAR],
fun(Path, _NodeProps) ->
io:format("Path ~0p~n", [Path])
end).get(PathPattern)
-spec get(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:payload_ret().
Returns the payload of the tree node pointed to by the given path pattern.
Calling this function is the same as callingget(StoreId, PathPattern) with the default store ID (see khepri_cluster:get_default_store_id/0).
get(StoreId, PathPattern)
-spec get(StoreId, PathPattern) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Ret :: khepri:payload_ret(); (PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:payload_ret().
Returns the payload of the tree node pointed to by the given path pattern.
This function accepts the following two forms:get(StoreId, PathPattern). Calling it is the same as callingget(StoreId, PathPattern, #{}).get(PathPattern, Options). Calling it is the same as callingget(StoreId, PathPattern, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: get/3.
get(StoreId, PathPattern, Options)
-spec get(StoreId, PathPattern, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:payload_ret().
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.
value %% Query the tree node at `/:foo/:bar'.
{ok, value} = khepri:get(StoreId, [foo, bar]). %% Query the tree node at `/:no_payload'.
{ok, undefined} = khepri:get(StoreId, [no_payload]). %% Query the tree node at `/:non_existent'.
{error, ?khepri_error(node_not_found, _)} = khepri:get(
StoreId, [non_existent]).See also: get_many/3, get_or/3, khepri_adv:get/3.
get!(PathPattern)
-spec 'get!'(PathPattern) -> Payload when PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_payload_ret().
get!(StoreId, PathPattern)
-spec 'get!'(StoreId, PathPattern) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_payload_ret(); (PathPattern, Options) -> Payload when PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), Payload :: khepri:unwrapped_payload_ret().
get!(StoreId, PathPattern, Options)
-spec 'get!'(StoreId, PathPattern, Options) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), Payload :: khepri:unwrapped_payload_ret().
get_many(PathPattern)
-spec get_many(PathPattern) -> Ret when PathPattern :: khepri_path:pattern(), Ret :: khepri:many_payloads_ret().
Returns payloads of all the tree nodes matching the given path pattern.
Calling this function is the same as callingget_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(StoreId, PathPattern)
-spec get_many(StoreId, PathPattern) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Ret :: khepri:many_payloads_ret(); (PathPattern, Options) -> Ret when PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:many_payloads_ret().
Returns payloads of all the tree nodes matching the given path pattern.
This function accepts the following two forms:get_many(StoreId, PathPattern). Calling it is the same as callingget_many(StoreId, PathPattern, #{}).get_many(PathPattern, Options). Calling it is the same as callingget_many(StoreId, PathPattern, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: get_many/3.
get_many(StoreId, PathPattern, Options)
-spec get_many(StoreId, PathPattern, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:many_payloads_ret().
Returns payloads of all the tree nodes matching the given path pattern.
Calling this function is the same as calling get_many_or(StoreId, PathPattern, undefined, Options).
The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.
The returned {ok, PayloadsMap} tuple contains a map where keys correspond to the path to a tree node matching the path pattern. Each key then points to the payload of that matching tree node, or Default if the tree node had no payload.
%% Get all nodes in the tree. The tree is:
%% <root>
%% `-- foo
%% `-- bar = value
{ok, #{[foo] := undefined,
[foo, bar] := value}} = khepri:get_many(
StoreId,
[?KHEPRI_WILDCARD_STAR_STAR]).See also: get/3, get_many_or/4, khepri_adv:get_many/3.
get_many!(PathPattern)
-spec 'get_many!'(PathPattern) -> Payload when PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_many_payloads_ret().
get_many!(StoreId, PathPattern)
-spec 'get_many!'(StoreId, PathPattern) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Payload :: khepri:unwrapped_many_payloads_ret(); (PathPattern, Options) -> Payload when PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), Payload :: khepri:unwrapped_many_payloads_ret().
get_many!(StoreId, PathPattern, Options)
-spec 'get_many!'(StoreId, PathPattern, Options) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), Payload :: khepri:unwrapped_many_payloads_ret().
get_many_or(PathPattern, Default)
-spec get_many_or(PathPattern, Default) -> Ret when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Ret :: khepri:many_payloads_ret(Default).
Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
Calling this function is the same as callingget_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(StoreId, PathPattern, Default)
-spec get_many_or(StoreId, PathPattern, Default) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Ret :: khepri:many_payloads_ret(Default); (PathPattern, Default, Options) -> Ret when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:many_payloads_ret(Default).
Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
This function accepts the following two forms:get_many_or(StoreId, PathPattern, Default). Calling it is the same as callingget_many_or(StoreId, PathPattern, Default, #{}).get_many_or(PathPattern, Default, Options). Calling it is the same as callingget_many_or(StoreId, PathPattern, Default, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: get_many_or/4.
get_many_or(StoreId, PathPattern, Default, Options)
-spec get_many_or(StoreId, PathPattern, Default, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:many_payloads_ret(Default).
Returns payloads of all the tree nodes matching the given path pattern, or a default payload.
The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.
The returned {ok, PayloadsMap} tuple contains a map where keys correspond to the path to a tree node matching the path pattern. Each key then points to the payload of that matching tree node, or Default if the tree node had no payload.
%% Get all nodes in the tree. The tree is:
%% <root>
%% `-- foo
%% `-- bar = value
{ok, #{[foo] := default,
[foo, bar] := value}} = khepri:get_many_or(
StoreId,
[?KHEPRI_WILDCARD_STAR_STAR],
default).See also: get_many/3, get_or/4, khepri_adv:get_many/3.
get_many_or!(PathPattern, Default)
-spec 'get_many_or!'(PathPattern, Default) -> Payload when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Payload :: khepri:unwrapped_many_payloads_ret().
get_many_or!(StoreId, PathPattern, Default)
-spec 'get_many_or!'(StoreId, PathPattern, Default) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Payload :: khepri:unwrapped_many_payloads_ret(); (PathPattern, Default, Options) -> Payload when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Options :: query_options() | khepri:tree_options(), Payload :: khepri:unwrapped_many_payloads_ret().
get_many_or!(StoreId, PathPattern, Default, Options)
-spec 'get_many_or!'(StoreId, PathPattern, Default, Options) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Options :: query_options() | khepri:tree_options(), Payload :: khepri:unwrapped_many_payloads_ret().
get_or(PathPattern, Default)
-spec get_or(PathPattern, Default) -> Ret when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Ret :: khepri:payload_ret(Default).
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 callingget_or(StoreId, PathPattern, Default) with the default store ID (see khepri_cluster:get_default_store_id/0).
get_or(StoreId, PathPattern, Default)
-spec get_or(StoreId, PathPattern, Default) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Ret :: khepri:payload_ret(Default); (PathPattern, Default, Options) -> Ret when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:payload_ret(Default).
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:get_or(StoreId, PathPattern, Default). Calling it is the same as callingget_or(StoreId, PathPattern, Default, #{}).get_or(PathPattern, Default, Options). Calling it is the same as callingget_or(StoreId, PathPattern, Default, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: get_or/4.
get_or(StoreId, PathPattern, Default, Options)
-spec get_or(StoreId, PathPattern, Default, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:payload_ret(Default).
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.
value %% Query the tree node at `/:foo/:bar'.
{ok, value} = khepri:get_or(StoreId, [foo, bar], default). %% Query the tree node at `/:no_payload'.
{ok, default} = khepri:get_or(StoreId, [no_payload], default). %% Query the tree node at `/:non_existent'.
{ok, default} = khepri:get_or(StoreId, [non_existent], default).See also: get/3, get_many_or/4, khepri_adv:get/3.
get_or!(PathPattern, Default)
-spec 'get_or!'(PathPattern, Default) -> Payload when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Payload :: khepri:unwrapped_payload_ret().
get_or!(StoreId, PathPattern, Default)
-spec 'get_or!'(StoreId, PathPattern, Default) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Payload :: khepri:unwrapped_payload_ret(); (PathPattern, Default, Options) -> Payload when PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Options :: query_options() | khepri:tree_options(), Payload :: khepri:unwrapped_payload_ret().
get_or!(StoreId, PathPattern, Default, Options)
-spec 'get_or!'(StoreId, PathPattern, Default, Options) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Default :: khepri:data(), Options :: query_options() | khepri:tree_options(), Payload :: khepri:unwrapped_payload_ret().
get_store_ids()
-spec get_store_ids() -> [StoreId] when StoreId :: store_id().
See also: khepri_cluster:get_store_ids/0.
has_data(PathPattern)
-spec has_data(PathPattern) -> HasData | Error when PathPattern :: khepri_path:pattern(), HasData :: boolean(), Error :: khepri:error().
Indicates if the tree node pointed to by the given path has data or not.
Calling this function is the same as callinghas_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(StoreId, PathPattern)
-spec has_data(StoreId, PathPattern) -> HasData | Error when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), HasData :: boolean(), Error :: khepri:error(); (PathPattern, Options) -> HasData | Error when PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), HasData :: boolean(), Error :: khepri:error().
Indicates if the tree node pointed to by the given path has data or not.
This function accepts the following two forms:has_data(StoreId, PathPattern). Calling it is the same as callinghas_data(StoreId, PathPattern, #{}).has_data(PathPattern, Options). Calling it is the same as callinghas_data(StoreId, PathPattern, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: has_data/3.
has_data(StoreId, PathPattern, Options)
-spec has_data(StoreId, PathPattern, Options) -> HasData | Error when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), HasData :: boolean(), Error :: khepri:error().
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.
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!(PathPattern)
-spec 'has_data!'(PathPattern) -> HasData when PathPattern :: khepri_path:pattern(), HasData :: boolean().
has_data!(StoreId, PathPattern)
-spec 'has_data!'(StoreId, PathPattern) -> HasData when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), HasData :: boolean(); (PathPattern, Options) -> HasData when PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), HasData :: boolean().
has_data!(StoreId, PathPattern, Options)
-spec 'has_data!'(StoreId, PathPattern, Options) -> HasData when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), HasData :: boolean().
import(Module, ModulePriv)
-spec import(Module, ModulePriv) -> Ret when Module :: module(), ModulePriv :: khepri_import_export:module_priv(), Ret :: ok | {ok, ModulePriv} | {error, any()}.
Imports a previously exported set of tree nodes using the Module callback module.
import(StoreId, Module, ModulePriv) with the default store ID (see khepri_cluster:get_default_store_id/0).See also: import/3.
import(StoreId, Module, ModulePriv)
-spec import(StoreId, Module, ModulePriv) -> Ret when StoreId :: khepri:store_id(), Module :: module(), ModulePriv :: khepri_import_export:module_priv(), Ret :: ok | {ok, ModulePriv} | {error, any()}.
Imports a previously exported set of tree nodes using the Module callback module.
Module is the callback module called to perform the actual import. It must conform to the Mnesia Backup & Restore API. See khepri_import_export for more details.
ModulePriv is the term passed to khepri_import_export:open_read/1.
Importing something doesn't delete existing tree nodes. The caller is responsible for deleting the existing content of a store if he needs to.
Example: import a set of tree nodes usingkhepri_export_erlang as the callback module ok = khepri:import(StoreId, khepri_export_erlang, "export-1.erl").See also: export/3.
info()
-spec info() -> ok.
info(StoreId)
-spec info(StoreId) -> ok when StoreId :: store_id().
info(StoreId, Options)
-spec info(StoreId, Options) -> ok when StoreId :: khepri:store_id(), Options :: khepri:query_options().
is_sproc(PathPattern)
-spec is_sproc(PathPattern) -> IsSproc | Error when PathPattern :: khepri_path:pattern(), IsSproc :: boolean(), Error :: khepri: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 callingis_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(StoreId, PathPattern)
-spec is_sproc(StoreId, PathPattern) -> IsSproc | Error when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), IsSproc :: boolean(), Error :: khepri:error(); (PathPattern, Options) -> IsSproc | Error when PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), IsSproc :: boolean(), Error :: khepri: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:is_sproc(StoreId, PathPattern). Calling it is the same as callingis_sproc(StoreId, PathPattern, #{}).is_sproc(PathPattern, Options). Calling it is the same as callingis_sproc(StoreId, PathPattern, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: is_sproc/3.
is_sproc(StoreId, PathPattern, Options)
-spec is_sproc(StoreId, PathPattern, Options) -> IsSproc | Error when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Options :: khepri:query_options() | khepri:tree_options(), IsSproc :: boolean(), Error :: khepri:error().
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.
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!(PathPattern)
-spec 'is_sproc!'(PathPattern) -> IsSproc when PathPattern :: khepri_path:pattern(), IsSproc :: boolean().
is_sproc!(StoreId, PathPattern)
-spec 'is_sproc!'(StoreId, PathPattern) -> IsSproc when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), IsSproc :: boolean(); (PathPattern, Options) -> IsSproc when PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), IsSproc :: boolean().
is_sproc!(StoreId, PathPattern, Options)
-spec 'is_sproc!'(StoreId, PathPattern, Options) -> IsSproc when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Options :: query_options() | khepri:tree_options(), IsSproc :: boolean().
map(PathPattern, Fun)
-spec map(PathPattern, Fun) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:map_fun(), Ret :: khepri:ok(Map) | khepri:error(), Map :: #{khepri_path:native_path() => khepri:map_fun_ret()}.
Produces a new map by calling Fun for each tree node matching the given path pattern.
map(StoreId, PathPattern, Fun) with the default store ID (see khepri_cluster:get_default_store_id/0).
map(StoreId, PathPattern, Fun)
-spec map(StoreId, PathPattern, Fun) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Fun :: khepri:map_fun(), Ret :: khepri:ok(Map) | khepri:error(), Map :: #{khepri_path:native_path() => khepri:map_fun_ret()}; (PathPattern, Fun, Options) -> Ret when PathPattern :: khepri_path:pattern(), Fun :: khepri:map_fun(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:ok(Map) | khepri:error(), Map :: #{khepri_path:native_path() => khepri:map_fun_ret()}.
Produces a new map by calling Fun for each tree node matching the given path pattern.
map(StoreId, PathPattern, Fun). Calling it is the same as callingmap(StoreId, PathPattern, Fun, #{}).map(PathPattern, Fun, Options). Calling it is the same as callingmap(StoreId, PathPattern, Fun, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: map/4.
map(StoreId, PathPattern, Fun, Options)
-spec map(StoreId, PathPattern, Fun, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Fun :: khepri:map_fun(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: khepri:ok(Map) | khepri:error(), Map :: #{khepri_path:native_path() => khepri:map_fun_ret()}.
Produces a new map by calling Fun for each tree node matching the given path pattern.
The produced map uses the tree node path as the key, like get_many/3 and the return value of Fun as the value.
The PathPattern can be provided as a native path pattern (a list of tree node names and conditions) or as a string. See khepri_path:from_string/1.
maps:map/2, Fun must accept the following arguments:- the native path of the tree node being handled
- the tree node properties map
%% The tree is:
%% <root>
%% `-- foo
%% `-- bar = value
{ok, #{[foo] => "/:foo",
[foo, bar] => "/:foo/:bar"}} = khepri:map(
StoreId,
[?KHEPRI_WILDCARD_STAR_STAR],
fun(Path, _NodeProps) ->
khepri_path:to_string(Path)
end).put(PathPattern, Data)
-spec put(PathPattern, Data) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Sets the payload of the tree node pointed to by the given path pattern.
Calling this function is the same as callingput(StoreId, PathPattern, Data) with the default store ID (see khepri_cluster:get_default_store_id/0).
put(StoreId, PathPattern, Data)
-spec put(StoreId, PathPattern, Data) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Sets the payload of the tree node pointed to by the given path pattern.
Calling this function is the same as callingput(StoreId, PathPattern, Data, #{}).See also: put/4.
put(StoreId, PathPattern, Data, Options)
-spec put(StoreId, PathPattern, Data, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret() | khepri_machine:async_ret().
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:- An explicit absence of payload (
khepri_payload:no_payload()), using the marker returned bykhepri_payload:none/0, meaning there will be no payload attached to the tree node and the existing payload will be discarded if any - An anonymous function; it will be considered a stored procedure and will be wrapped in a
khepri_payload:sproc()record - Any other term; it will be wrapped in a
khepri_payload:data()record
It is possible to wrap the payload in its internal structure explicitly using the khepri_payload module directly.
The Options map may specify command-level options; see khepri:command_options(), khepri:tree_options() and khepri:put_options().
When doing an asynchronous update, the wait_for_async_ret/1 function can be used to receive the message from Ra.
%% 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!(PathPattern, Data)
-spec 'put!'(PathPattern, Data) -> Payload when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Payload :: khepri:unwrapped_minimal_ret().
put!(StoreId, PathPattern, Data)
-spec 'put!'(StoreId, PathPattern, Data) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Payload :: khepri:unwrapped_minimal_ret().
put!(StoreId, PathPattern, Data, Options)
-spec 'put!'(StoreId, PathPattern, Data, Options) -> Ret when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
put_many(PathPattern, Data)
-spec put_many(PathPattern, Data) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Sets the payload of all the tree nodes matching the given path pattern.
Calling this function is the same as callingput_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(StoreId, PathPattern, Data)
-spec put_many(StoreId, PathPattern, Data) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Sets the payload of all the tree nodes matching the given path pattern.
Calling this function is the same as callingput_many(StoreId, PathPattern, Data, #{}).See also: put_many/4.
put_many(StoreId, PathPattern, Data, Options)
-spec put_many(StoreId, PathPattern, Data, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret() | khepri_machine:async_ret().
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:- An explicit absence of payload (
khepri_payload:no_payload()), using the marker returned bykhepri_payload:none/0, meaning there will be no payload attached to the tree node and the existing payload will be discarded if any - An anonymous function; it will be considered a stored procedure and will be wrapped in a
khepri_payload:sproc()record - Any other term; it will be wrapped in a
khepri_payload:data()record
It is possible to wrap the payload in its internal structure explicitly using the khepri_payload module directly.
The Options map may specify command-level options; see khepri:command_options(), khepri:tree_options() and khepri:put_options().
When doing an asynchronous update, the wait_for_async_ret/1 function can be used to receive the message from Ra.
%% 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.
put_many!(PathPattern, Data)
-spec 'put_many!'(PathPattern, Data) -> Payload when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Payload :: khepri:unwrapped_minimal_ret().
put_many!(StoreId, PathPattern, Data)
-spec 'put_many!'(StoreId, PathPattern, Data) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Payload :: khepri:unwrapped_minimal_ret().
put_many!(StoreId, PathPattern, Data, Options)
-spec 'put_many!'(StoreId, PathPattern, Data, Options) -> Ret when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
register_projection(PathPattern, Projection)
-spec register_projection(PathPattern, Projection) -> Ret when PathPattern :: khepri_path:pattern(), Projection :: khepri_projection:projection(), Ret :: ok | khepri:error().
Registers a projection.
Calling this function is the same as callingregister_projection(StoreId, PathPattern, Projection) with the default store ID (see khepri_cluster:get_default_store_id/0).See also: register_projection/3.
register_projection(StoreId, PathPattern, Projection)
-spec register_projection(StoreId, PathPattern, Projection) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Projection :: khepri_projection:projection(), Ret :: ok | khepri:error(); (PathPattern, Projection, Options) -> Ret when PathPattern :: khepri_path:pattern(), Projection :: khepri_projection:projection(), Options :: khepri:command_options(), Ret :: ok | khepri:error().
Registers a projection.
This function accepts the following two forms:register_projection(StoreId, PathPattern, Projection). Calling it is the same as callingregister_projection(StoreId, PathPattern, Projection, #{}).register_projection(PathPattern, Projection, Options). Calling it is the same as callingregister_projection(StoreId, PathPattern, Projection, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: register_projection/4.
register_projection(StoreId, PathPattern, Projection, Options)
-spec register_projection(StoreId, PathPattern, Projection, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Projection :: khepri_projection:projection(), Options :: khepri:command_options(), Ret :: ok | khepri:error().
Registers a projection.
A projection is a replicated ETS cache which is kept up to date by Khepri. See the khepri_projection module-docs for more information about projections.
This function associates a projection created with khepri_projection:new/3 with a pattern. Any changes to tree nodes matching the provided pattern will be turned into records using the projection's khepri_projection:projection_fun() and then applied to the projection's ETS table.
PathPattern and are already in the store.
register_trigger(TriggerId, EventFilter, StoredProcPath)
-spec register_trigger(TriggerId, EventFilter, StoredProcPath) -> Ret when TriggerId :: trigger_id(), EventFilter :: khepri_evf:event_filter() | khepri_path:pattern(), StoredProcPath :: khepri_path:path(), Ret :: ok | error().
Registers a trigger.
Calling this function is the same as callingregister_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(StoreId, TriggerId, EventFilter, StoredProcPath)
-spec register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath) -> Ret when StoreId :: khepri:store_id(), TriggerId :: trigger_id(), EventFilter :: khepri_evf:event_filter() | khepri_path:pattern(), StoredProcPath :: khepri_path:path(), Ret :: ok | error(); (TriggerId, EventFilter, StoredProcPath, Options) -> Ret when TriggerId :: trigger_id(), EventFilter :: khepri_evf:event_filter() | khepri_path:pattern(), StoredProcPath :: khepri_path:path(), Options :: command_options() | khepri:tree_options(), Ret :: ok | error().
Registers a trigger.
This function accepts the following two forms:register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath). Calling it is the same as callingregister_trigger(StoreId, TriggerId, EventFilter, StoredProcPath, #{}).register_trigger(TriggerId, EventFilter, StoredProcPath, Options). Calling it is the same as callingregister_trigger(StoreId, TriggerId, EventFilter, StoredProcPath, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: register_trigger/5.
register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath, Options)
-spec register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath, Options) -> Ret when StoreId :: khepri:store_id(), TriggerId :: trigger_id(), EventFilter :: khepri_evf:event_filter() | khepri_path:pattern(), StoredProcPath :: khepri_path:path(), Options :: command_options() | khepri:tree_options(), Ret :: ok | error().
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.reset()
-spec reset() -> Ret when Ret :: ok | error().
See also: khepri_cluster:reset/0.
reset(StoreIdOrTimeout)
-spec reset(StoreId | Timeout) -> Ret when StoreId :: khepri:store_id(), Timeout :: timeout(), Ret :: ok | khepri:error().
See also: khepri_cluster:reset/1.
reset(StoreId, Timeout)
-spec reset(StoreId, Timeout) -> Ret when StoreId :: khepri:store_id(), Timeout :: timeout(), Ret :: ok | error().
See also: khepri_cluster:reset/2.
run_sproc(PathPattern, Args)
-spec run_sproc(PathPattern, Args) -> Ret when PathPattern :: khepri_path:pattern(), Args :: list(), Ret :: any().
Runs the stored procedure pointed to by the given path and returns the result.
Calling this function is the same as callingrun_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(StoreId, PathPattern, Args)
-spec run_sproc(StoreId, PathPattern, Args) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Args :: list(), Ret :: any(); (PathPattern, Args, Options) -> Ret when PathPattern :: khepri_path:pattern(), Args :: list(), Options :: khepri:query_options() | khepri:tree_options(), Ret :: any().
Runs the stored procedure pointed to by the given path and returns the result.
This function accepts the following two forms:run_sproc(StoreId, PathPattern, Args). Calling it is the same as callingrun_sproc(StoreId, PathPattern, Args, #{}).run_sproc(PathPattern, Args, Options). Calling it is the same as callingrun_sproc(StoreId, PathPattern, Args, Options)with the default store ID (seekhepri_cluster:get_default_store_id/0).
See also: run_sproc/4.
run_sproc(StoreId, PathPattern, Args, Options)
-spec run_sproc(StoreId, PathPattern, Args, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Args :: list(), Options :: khepri:query_options(), Ret :: any().
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.
Args list must match the number of arguments expected by the stored procedure.See also: is_sproc/3.
start()
-spec start() -> Ret when Ret :: khepri:ok(StoreId) | khepri:error(), StoreId :: khepri:store_id().
See also: khepri_cluster:start/0.
start(RaSystemOrDataDir)
-spec start(RaSystem | DataDir) -> Ret when RaSystem :: atom(), DataDir :: file:filename_all(), Ret :: khepri:ok(StoreId) | khepri:error(), StoreId :: khepri:store_id().
See also: khepri_cluster:start/1.
start(RaSystemOrDataDir, StoreIdOrRaServerConfig)
-spec start(RaSystem | DataDir, StoreId | RaServerConfig) -> Ret when RaSystem :: atom(), DataDir :: file:filename_all(), StoreId :: store_id(), RaServerConfig :: khepri_cluster:incomplete_ra_server_config(), Ret :: khepri:ok(StoreId) | khepri:error(), StoreId :: khepri:store_id().
See also: khepri_cluster:start/2.
start(RaSystemOrDataDir, StoreIdOrRaServerConfig, Timeout)
-spec start(RaSystem | DataDir, StoreId | RaServerConfig, Timeout) -> Ret when RaSystem :: atom(), DataDir :: file:filename_all(), StoreId :: store_id(), RaServerConfig :: khepri_cluster:incomplete_ra_server_config(), Timeout :: timeout(), Ret :: khepri:ok(StoreId) | khepri:error(), StoreId :: khepri:store_id().
See also: khepri_cluster:start/3.
stop()
-spec stop() -> Ret when Ret :: ok | khepri:error().
See also: khepri_cluster:stop/0.
stop(StoreId)
-spec stop(StoreId) -> Ret when StoreId :: khepri:store_id(), Ret :: ok | khepri:error().
See also: khepri_cluster:stop/1.
transaction(FunOrPath)
-spec transaction(FunOrPath) -> Ret when FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), Ret :: khepri_machine:tx_ret().
Runs a transaction and returns its result.
Calling this function is the same as callingtransaction(FunOrPath, []) with the default store ID.See also: transaction/2.
transaction(StoreId, FunOrPath)
-spec transaction(StoreId, FunOrPath) -> Ret when StoreId :: store_id(), FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), Ret :: khepri_machine:tx_ret(); (FunOrPath, Args) -> Ret when FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), Args :: list(), Ret :: khepri_machine:tx_ret(); (FunOrPath, ReadWriteOrOptions) -> Ret when FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), ReadWriteOrOptions :: ReadWrite | Options, ReadWrite :: ro | rw | auto, Options :: command_options() | query_options(), Ret :: khepri_machine:tx_ret() | khepri_machine:async_ret().
Runs a transaction and returns its result.
This function accepts the following two forms:transaction(StoreId, FunOrPath). Calling it is the same as callingtransaction(StoreId, FunOrPath, []).transaction(FunOrPath, Args). Calling it is the same as callingtransaction(StoreId, FunOrPath, Args)with the default store ID.transaction(FunOrPath, ReadWriteOrOptions). Calling it is the same as callingtransaction(StoreId, FunOrPath, [], ReadWriteOrOptions)with the default store ID.
See also: transaction/3.
transaction(StoreId, FunOrPath, Args)
-spec transaction(StoreId, FunOrPath, Args) -> Ret when StoreId :: store_id(), FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), Args :: list(), Ret :: khepri_machine:tx_ret(); (StoreId, FunOrPath, ReadWriteOrOptions) -> Ret when StoreId :: store_id(), FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), ReadWriteOrOptions :: ReadWrite | Options, ReadWrite :: ro | rw | auto, Options :: command_options() | query_options(), Ret :: khepri_machine:tx_ret() | khepri_machine:async_ret(); (FunOrPath, Args, ReadWriteOrOptions) -> Ret when FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), Args :: list(), ReadWriteOrOptions :: ReadWrite | Options, ReadWrite :: ro | rw | auto, Options :: command_options() | query_options(), Ret :: khepri_machine:tx_ret() | khepri_machine:async_ret(); (FunOrPath, ReadWrite, Options) -> Ret when FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), ReadWrite :: ro | rw | auto, Options :: command_options() | query_options(), Ret :: khepri_machine:tx_ret() | khepri_machine:async_ret().
Runs a transaction and returns its result.
This function accepts the following two forms:transaction(StoreId, FunOrPath, Args). Calling it is the same as callingtransaction(StoreId, FunOrPath, Args, auto).transaction(StoreId, FunOrPath, ReadWriteOrOptions). Calling it is the same as callingtransaction(StoreId, FunOrPath, [], ReadWriteOrOptions).transaction(FunOrPath, Args, ReadWriteOrOptions). Calling it is the same as callingtransaction(StoreId, FunOrPath, Args, ReadWriteOrOptions)with the default store ID.
See also: transaction/4.
transaction(StoreId, FunOrPath, Args, ReadWrite)
-spec transaction(StoreId, FunOrPath, Args, ReadWrite) -> Ret when StoreId :: store_id(), FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), Args :: list(), ReadWrite :: ro | rw | auto, Ret :: khepri_machine:tx_ret(); (StoreId, FunOrPath, Args, Options) -> Ret when StoreId :: store_id(), FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), Args :: list(), Options :: command_options() | query_options(), Ret :: khepri_machine:tx_ret() | khepri_machine:async_ret(); (StoreId, FunOrPath, ReadWrite, Options) -> Ret when StoreId :: store_id(), FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), ReadWrite :: ro | rw | auto, Options :: command_options() | query_options(), Ret :: khepri_machine:tx_ret() | khepri_machine:async_ret(); (FunOrPath, Args, ReadWrite, Options) -> Ret when FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), Args :: list(), ReadWrite :: ro | rw | auto, Options :: command_options() | query_options(), Ret :: khepri_machine:tx_ret() | khepri_machine:async_ret().
Runs a transaction and returns its result.
This function accepts the following three forms:transaction(StoreId, FunOrPath, Args, ReadWrite). Calling it is the same as callingtransaction(StoreId, FunOrPath, Args, ReadWrite, #{}).transaction(StoreId, FunOrPath, Args, Options). Calling it is the same as callingtransaction(StoreId, FunOrPath, Args, auto, Options).transaction(FunOrPath, Args, ReadWrite, Options). Calling it is the same as callingtransaction(StoreId, FunOrPath, Args, ReadWrite, Options)with the default store ID.
See also: transaction/5.
transaction(StoreId, FunOrPath, Args, ReadWrite, Options)
-spec transaction(StoreId, FunOrPath, Args, ReadWrite, Options) -> Ret when StoreId :: store_id(), FunOrPath :: Fun | PathPattern, Fun :: khepri_tx:tx_fun(), PathPattern :: khepri_path:pattern(), Args :: list(), ReadWrite :: ro | rw | auto, Options :: khepri:command_options() | khepri:query_options(), Ret :: khepri_machine:tx_ret() | khepri_machine:async_ret().
Runs a transaction and returns its result.
Fun is an arbitrary anonymous function which takes the content of Args as its arguments. In other words, the length of Args must correspond to the arity of Fun.
Instead of Fun, PathPattern` can be passed. It must point to an existing stored procedure. The length to `Args must correspond to the arity of that stored procedure.
The ReadWrite flag determines what the Fun anonymous function is allowed to do and in which context it runs:
- If
ReadWriteisro,Funcan do whatever it wants, except modify the content of the store. In other words, uses ofkhepri_tx:put/2orkhepri_tx:delete/1are forbidden and will abort the function.Funis executed from a process on the leader Ra member. - If
ReadWriteisrw,Funcan use thekhepri_txtransaction API as well as any calls to other modules as long as those functions or what they do is permitted. Seekhepri_txfor more details. IfFundoes or calls something forbidden, the transaction will be aborted.Funis executed in the context of the state machine process on each Ra members. - If
ReadWriteisauto,Funis analyzed to determine if it callskhepri_tx:put/2orkhepri_tx:delete/1, or uses any denied operations for a read/write transaction. If it does, this is the same as settingReadWriteto true. Otherwise, this is the equivalent of settingReadWriteto false.
When using PathPattern, a ReadWrite of auto is synonymous of rw.
Options is relevant for both read-only and read-write transactions (including audetected ones). However note that both types expect different options.
FunOrPath can be any term. That result is returned in an {ok, Result} tuple if the transaction is synchronous. The result is sent by message if the transaction is asynchronous and a correlation ID was specified.
update(PathPattern, Data)
-spec update(PathPattern, Data) -> Ret when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Updates an existing tree node with the given payload.
Calling this function is the same as callingupdate(StoreId, PathPattern, Data) with the default store ID (see khepri_cluster:get_default_store_id/0).
update(StoreId, PathPattern, Data)
-spec update(StoreId, PathPattern, Data) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Ret :: khepri:minimal_ret().
Updates an existing tree node with the given payload.
Calling this function is the same as callingupdate(StoreId, PathPattern, Data, #{}).See also: update/4.
update(StoreId, PathPattern, Data, Options)
-spec update(StoreId, PathPattern, Data, Options) -> Ret when StoreId :: khepri:store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | khepri:data() | fun(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:minimal_ret() | khepri_machine:async_ret().
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.
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.
update!(PathPattern, Data)
-spec 'update!'(PathPattern, Data) -> Payload when PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Payload :: khepri:unwrapped_minimal_ret().
update!(StoreId, PathPattern, Data)
-spec 'update!'(StoreId, PathPattern, Data) -> Payload when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Payload :: khepri:unwrapped_minimal_ret().
update!(StoreId, PathPattern, Data, Options)
-spec 'update!'(StoreId, PathPattern, Data, Options) -> Ret when StoreId :: store_id(), PathPattern :: khepri_path:pattern(), Data :: khepri_payload:payload() | data() | fun(), Options :: khepri:command_options() | khepri:tree_options() | khepri:put_options(), Ret :: khepri:unwrapped_minimal_ret() | khepri_machine:async_ret().
wait_for_async_ret(Correlation)
-spec wait_for_async_ret(Correlation) -> Ret when Correlation :: ra_server:command_correlation(), Ret :: khepri:minimal_ret() | khepri:payload_ret() | khepri:many_payloads_ret() | khepri_adv:single_result() | khepri_adv:many_results() | khepri_machine:tx_ret().
Waits for an asynchronous call.
Calling this function is the same as callingwait_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(Correlation, Timeout)
-spec wait_for_async_ret(Correlation, Timeout) -> Ret when Correlation :: ra_server:command_correlation(), Timeout :: timeout(), Ret :: khepri:minimal_ret() | khepri:payload_ret() | khepri:many_payloads_ret() | khepri_adv:single_result() | khepri_adv:many_results() | khepri_machine:tx_ret().
Waits for an asynchronous call.
This function waits maximumTimeout 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.