Khepri database API.
This module exposes the database API to manipulate data.
The API is mainly made of the functions used to perform simple direct
atomic operations and queries on the database. In addition to that, transaction/1
are the starting point to run transaction functions. However
the API to use inside transaction functions is provided by khepri_tx
.
This module also provides functions to start and stop a simple unclustered
Khepri store. For more advanced setup and clustering, see khepri_cluster
.
A Khepri store is one instance of Khepri running inside a Ra cluster (which could be made of a single Erlang node). It is possible to run multiple Khepri stores in parallel by creating multiple Ra clusters.
A Khepri store is started and configured with start/0
, start/1
or start/3
. To setup a cluster, see khepri_cluster
.
When a store is started, a store ID store_id/0
is returned. This
store ID is then used by the rest of this module's API. The returned store
ID currently corresponds exactly to the Ra cluster name. It must be an atom
though; other types are unsupported.
get/1
, exists/1
, has_data/1
, etc.put/2
, delete/1
, etc.transaction/1
, etc.:
khepri:transaction(
fun() ->
khepri_tx:put(Path, Value)
end).
Simple operations are more efficient than transactions, but transactions are
more flexible.
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:true
to perform an asynchronous low-priority command without a
correlation ID.false
to perform a synchronous command.child_list_length() = non_neg_integer()
Number of direct child nodes under a tree node.
child_list_version() = pos_integer()
Number of changes made to the list of child nodes of a node (child nodes added or removed).
The child list version starts at 1 when a node is created. It is increased by 1 each time a child is added or removed. Changes made to existing nodes are not reflected in this version.command_options() = #{timeout => timeout(), async => async_option()}
Options used in commands.
Commands are put/5
, delete/3
and read-write transaction/4
.
timeout
is passed to Ra command processing function.async
indicates the synchronous or asynchronous nature of the
command; see async_option()
.data() = any()
Data stored in a node's payload.
error() = error(any())
The error tuple returned by a function after a failure.
error(Type) = {error, Type}
Return value of a failed command or query.
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:consistent
means that a "consistent query" will be used in Ra. It
will return the most up-to-date piece of data the cluster agreed on. Note
that it could block and eventually time out if there is no quorum in the Ra
cluster.compromise
performs "leader queries" most of the time to reduce
latency, but uses "consistent queries" every 10 seconds to verify that the
cluster is healthy on a regular basis. It should be faster but may block
and time out like consistent
and still return slightly out-of-date
data.low_latency
means that "local queries" are used exclusively. They are
the fastest and have the lowest latency. However, the returned data is
whatever the local Ra server has. It could be out-of-date if it has
troubles keeping up with the Ra cluster. The chance of blocking and timing
out is very small.node_props() = #{data => data(), sproc => khepri_fun:standalone_fun(), payload_version => payload_version(), child_list_version => child_list_version(), child_list_length => child_list_length(), child_nodes => #{khepri_path:node_id() => node_props()}}
Structure used to return properties, payload and child nodes for a specific node.
khepri_utils:flat_struct_to_tree/1
which may
construct fake node props without them.data
entry in this structure.node_props_map() = #{khepri_path:native_path() => node_props()}
Structure used to return a map of nodes and their associated properties, payload and child nodes.
This structure is used in the return value of all commands and queries.ok(Type) = {ok, Type}
The result of a function after a successful call, wrapped in an "ok" tuple.
payload_version() = pos_integer()
Number of changes made to the payload of a node.
The payload version starts at 1 when a node is created. It is increased by 1 each time the payload is added, modified or removed.query_options() = #{timeout => timeout(), expect_specific_node => boolean(), include_child_names => boolean(), favor => favor_option()}
Options used in queries.
timeout
is passed to Ra query processing function.expect_specific_node
indicates if the path is expected to point to a
specific tree node or could match many nodes.include_child_names
indicates if child names should be included in
the returned node properties map.favor
indicates where to put the cursor between freshness of the
returned data and low latency of queries; see favor_option()
.result() = khepri:ok(node_props_map()) | khepri:error()
Return value of a query or synchronous command.
store_id() = atom()
ID of a Khepri store.
This is the same as the Ra cluster name hosting the Khepri store.trigger_id() = atom()
An ID to identify a registered trigger.
start/0 | Starts a store. |
start/1 | Starts a store. |
start/2 | Starts a store. |
start/3 | Starts a store. |
reset/0 | Resets the store on this Erlang node. |
reset/1 | Resets the store on this Erlang node. |
reset/2 | Resets the store on this Erlang node. |
stop/0 | Stops a store. |
stop/1 | Stops a store. |
get_store_ids/0 | Returns the list of running stores. |
put/2 | Creates or modifies a specific tree node in the tree structure. |
put/3 | Creates or modifies a specific tree node in the tree structure. |
put/4 | Creates or modifies a specific tree node in the tree structure. |
put/5 | Creates or modifies a specific tree node in the tree structure. |
create/2 | Creates a specific tree node in the tree structure only if it does not exist. |
create/3 | Creates a specific tree node in the tree structure only if it does not exist. |
create/4 | Creates a specific tree node in the tree structure only if it does not exist. |
create/5 | Creates a specific tree node in the tree structure only if it does not exist. |
update/2 | Updates a specific tree node in the tree structure only if it already exists. |
update/3 | Updates a specific tree node in the tree structure only if it already exists. |
update/4 | Updates a specific tree node in the tree structure only if it already exists. |
update/5 | Updates a specific tree node in the tree structure only if it already exists. |
compare_and_swap/3 | Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern . |
compare_and_swap/4 | Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern . |
compare_and_swap/5 | Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern . |
compare_and_swap/6 | Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern . |
clear_payload/1 | Clears the payload of a specific tree node in the tree structure. |
clear_payload/2 | Clears the payload of a specific tree node in the tree structure. |
clear_payload/3 | Clears the payload of a specific tree node in the tree structure. |
clear_payload/4 | Clears the payload of a specific tree node in the tree structure. |
delete/1 | Deletes all tree nodes matching the path pattern. |
delete/2 | Deletes all tree nodes matching the path pattern. |
delete/3 | Deletes all tree nodes matching the path pattern. |
exists/1 | Returns true if the tree node pointed to by the given path exists,
otherwise false . |
exists/2 | Returns true if the tree node pointed to by the given path exists,
otherwise false . |
exists/3 | Returns true if the tree node pointed to by the given path exists,
otherwise false . |
get/1 | Returns all tree nodes matching the path pattern. |
get/2 | Returns all tree nodes matching the path pattern. |
get/3 | Returns all tree nodes matching the path pattern. |
get_node_props/1 | Returns the tree node properties associated with the given node path. |
get_node_props/2 | Returns the tree node properties associated with the given node path. |
get_node_props/3 | Returns the tree node properties associated with the given node path. |
has_data/1 | Returns true if the tree node pointed to by the given path has data,
otherwise false . |
has_data/2 | Returns true if the tree node pointed to by the given path has data,
otherwise false . |
has_data/3 | Returns true if the tree node pointed to by the given path has data,
otherwise false . |
get_data/1 | Returns the data associated with the given node path. |
get_data/2 | Returns the data associated with the given node path. |
get_data/3 | Returns the data associated with the given node path. |
get_data_or/2 | Returns the data associated with the given node path, or Default if
there is no data. |
get_data_or/3 | Returns the data associated with the given node path, or Default if
there is no data. |
get_data_or/4 | Returns the data associated with the given node path, or Default if
there is no data. |
has_sproc/1 | Returns true if the tree node pointed to by the given path holds a
stored procedure, otherwise false . |
has_sproc/2 | Returns true if the tree node pointed to by the given path holds a
stored procedure, otherwise false . |
has_sproc/3 | Returns true if the tree node pointed to by the given path holds a
stored procedure, otherwise false . |
run_sproc/2 | Runs the stored procedure pointed to by the given path and returns the result. |
run_sproc/3 | Runs the stored procedure pointed to by the given path and returns the result. |
run_sproc/4 | Runs the stored procedure pointed to by the given path and returns the result. |
count/1 | Counts all tree nodes matching the path pattern. |
count/2 | Counts all tree nodes matching the path pattern. |
count/3 | Counts all tree nodes matching the path pattern. |
register_trigger/3 | Registers a trigger. |
register_trigger/4 | Registers a trigger. |
register_trigger/5 | Registers a trigger. |
list/1 | Returns all direct child nodes under the given path. |
list/2 | Returns all direct child nodes under the given path. |
list/3 | Returns all direct child nodes under the given path. |
find/2 | Returns all tree nodes matching the path pattern. |
find/3 | Returns all tree nodes matching the path pattern. |
find/4 | Finds tree nodes under PathPattern which match the given Condition . |
transaction/1 | Runs a transaction and returns its result. |
transaction/2 | Runs a transaction and returns its result. |
transaction/3 | Runs a transaction and returns its result. |
transaction/4 | Runs a transaction and returns its result. |
clear_store/0 | Wipes out the entire tree. |
clear_store/1 | Wipes out the entire tree. |
clear_store/2 | Wipes out the entire tree. |
'put!'/2 | Creates or modifies a specific tree node in the tree structure. |
'put!'/3 | Creates or modifies a specific tree node in the tree structure. |
'put!'/4 | Creates or modifies a specific tree node in the tree structure. |
'put!'/5 | Creates or modifies a specific tree node in the tree structure. |
'create!'/2 | Creates a specific tree node in the tree structure only if it does not exist. |
'create!'/3 | Creates a specific tree node in the tree structure only if it does not exist. |
'create!'/4 | Creates a specific tree node in the tree structure only if it does not exist. |
'create!'/5 | Creates a specific tree node in the tree structure only if it does not exist. |
'update!'/2 | Updates a specific tree node in the tree structure only if it already exists. |
'update!'/3 | Updates a specific tree node in the tree structure only if it already exists. |
'update!'/4 | Updates a specific tree node in the tree structure only if it already exists. |
'update!'/5 | Updates a specific tree node in the tree structure only if it already exists. |
'compare_and_swap!'/3 | Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern . |
'compare_and_swap!'/4 | Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern . |
'compare_and_swap!'/5 | Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern . |
'compare_and_swap!'/6 | Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern . |
'get!'/1 | Returns all tree nodes matching the path pattern. |
'get!'/2 | Returns all tree nodes matching the path pattern. |
'get!'/3 | Returns all tree nodes matching the path pattern. |
'delete!'/1 | Deletes all tree nodes matching the path pattern. |
'delete!'/2 | Deletes all tree nodes matching the path pattern. |
'delete!'/3 | Deletes all tree nodes matching the path pattern. |
info/0 | Lists the running stores on stdout. |
info/1 | Lists the content of specified store on stdout. |
info/2 | Lists the content of specified store on stdout. |
start() -> Ret
Ret = khepri:ok(StoreId) | khepri:error()
StoreId = khepri:store_id()
Starts a store.
See also: khepri_cluster:start/0.
start(RaSystemOrDataDir::RaSystem | DataDir) -> Ret
RaSystem = atom()
DataDir = file:filename_all()
Ret = khepri:ok(StoreId) | khepri:error()
StoreId = khepri:store_id()
Starts a store.
See also: khepri_cluster:start/1.
start(RaSystemOrDataDir::RaSystem | DataDir, StoreIdOrRaServerConfig::StoreId | RaServerConfig) -> Ret
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()
Starts a store.
See also: khepri_cluster:start/2.
start(RaSystemOrDataDir::RaSystem | DataDir, StoreIdOrRaServerConfig::StoreId | RaServerConfig, Timeout) -> Ret
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()
Starts a store.
See also: khepri_cluster:start/3.
reset() -> Ret
Ret = ok | error()
Resets the store on this Erlang node.
See also: khepri_cluster:reset/0.
reset(StoreIdOrTimeout::StoreId | Timeout) -> Ret
StoreId = khepri:store_id()
Timeout = timeout()
Ret = ok | khepri:error()
Resets the store on this Erlang node.
See also: khepri_cluster:reset/1.
reset(StoreId, Timeout) -> Ret
StoreId = khepri:store_id()
Timeout = timeout()
Ret = ok | error()
Resets the store on this Erlang node.
See also: khepri_cluster:reset/2.
stop() -> Ret
Ret = ok | khepri:error()
Stops a store.
See also: khepri_cluster:stop/0.
stop(StoreId) -> Ret
StoreId = khepri:store_id()
Ret = ok | khepri:error()
Stops a store.
See also: khepri_cluster:stop/1.
get_store_ids() -> [StoreId]
StoreId = store_id()
Returns the list of running stores.
See also: khepri_cluster:get_store_ids/0.
put(PathPattern, Data) -> Result
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Result = result()
Creates or modifies a specific tree node in the tree structure.
Calling this function is the same as callingput(StoreId, PathPattern,
Data)
with the default store ID.
See also: put/3.
put(StoreId, PathPattern, Data) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Result = result()
Creates or modifies a specific tree node in the tree structure.
Calling this function is the same as callingput(StoreId, PathPattern,
Data, #{}, #{})
.
See also: put/5.
put(StoreId, PathPattern, Data, Extra::Extra | Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
Creates or modifies a specific tree node in the tree structure.
Calling this function is the same as callingput(StoreId, PathPattern,
Data, Extra, Options)
with an empty Extra
or Options
.
See also: put/5.
put(StoreId, PathPattern, Data, Extra, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the node to create or
modify.
Data
: the Erlang term or function to store, or a khepri_payload:payload()
structure.
Extra
: extra options such as keep_while
conditions.
Options
: command options such as the command type.
returns: in the case of a synchronous put, an {ok, Result}
tuple with a
map with one entry, or an {error, Reason}
tuple; in the case of an
asynchronous put, always ok
(the actual return value may be sent by a
message if a correlation ID was specified).
Creates or modifies a specific tree node in the tree structure.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
The path or path pattern must target a specific tree node. In other words, updating many nodes with the same payload is denied. That fact is checked before the node is looked up: so if a condition in the path could potentially match several nodes, an error is returned, even though only one node would match at the time.
When using a simple path (i.e. without conditions), if the target node does not exist, it is created using the given payload. If the target node exists, it is updated with the given payload and its payload version is increased by one. Missing parent nodes are created on the way.
When using a path pattern, the behavior is the same. However if a condition in the path pattern is not met, an error is returned and the tree structure is not modified.
If the target node is modified, the returned structure in the "ok" tuple will have a single key corresponding to the resolved path of the target node. The path will be the same as the argument if it was a simple path, or the final path after conditions were applied if it was a path pattern. That key will point to a map containing the properties and payload (if any) of the node before the modification.
If the target node is created, the returned structure in the "ok" tuple will have a single key corresponding to the path of the target node. That key will point to an empty map, indicating there was no existing node (i.e. there was no properties or payload to return).
The payload must be one of the following form:khepri_payload:no_payload()
),
using the marker returned by khepri_payload:none/0
, meaning there
will be no payload attached to the node and the existing payload will be
discarded if anykhepri_payload:sproc()
recordkhepri_payload:data()
recordIt is possible to wrap the payload in its internal structure explicitly
using the khepri_payload
module directly.
Extra
map may specify put-specific options:
keep_while
: keep_while
conditions to tie the life of the inserted
node to conditions on other nodes; see khepri_condition:keep_while()
.The Options
map may specify command-level options; see command_options()
.
%% Insert a node at `/:foo/:bar', overwriting the previous value.
Result = khepri:put(StoreId, [foo, bar], new_value),
%% Here is the content of `Result'.
{ok, #{[foo, bar] => #{data => old_value,
payload_version => 1,
child_list_version => 1,
child_list_length => 0}}} = Result.
create(PathPattern, Data) -> Result
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Result = result()
Creates a specific tree node in the tree structure only if it does not exist.
Calling this function is the same as callingcreate(StoreId, PathPattern,
Data)
with the default store ID.
See also: create/3.
create(StoreId, PathPattern, Data) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Result = result()
Creates a specific tree node in the tree structure only if it does not exist.
Calling this function is the same as callingcreate(StoreId, PathPattern,
Data, #{}, #{})
.
See also: create/5.
create(StoreId, PathPattern, Data, Extra::Extra | Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
Creates a specific tree node in the tree structure only if it does not exist.
Calling this function is the same as callingcreate(StoreId, PathPattern,
Data, Extra, Options)
with an empty Extra
or Options
.
See also: create/5.
create(StoreId, PathPattern, Data, Extra, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the node to create or
modify.
Data
: the Erlang term or function to store, or a khepri_payload:payload()
structure.
Extra
: extra options such as keep_while
conditions.
Options
: command options such as the command type.
returns: in the case of a synchronous put, an {ok, Result}
tuple with a
map with one entry, or an {error, Reason}
tuple; in the case of an
asynchronous put, always ok
(the actual return value may be sent by a
message if a correlation ID was specified).
Creates a specific tree node in the tree structure only if it does not exist.
Internally, thePathPattern
is modified to include an
#if_node_exists{exists = false}
condition on its last component.
Otherwise, the behavior is that of put/5
.
See also: put/5.
update(PathPattern, Data) -> Result
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Result = result()
Updates a specific tree node in the tree structure only if it already exists.
Calling this function is the same as callingupdate(StoreId, PathPattern,
Data)
with the default store ID.
See also: update/3.
update(StoreId, PathPattern, Data) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Result = result()
Updates a specific tree node in the tree structure only if it already exists.
Calling this function is the same as callingupdate(StoreId, PathPattern,
Data, #{}, #{})
.
See also: update/5.
update(StoreId, PathPattern, Data, Extra::Extra | Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
Updates a specific tree node in the tree structure only if it already exists.
Calling this function is the same as callingupdate(StoreId, PathPattern,
Data, Extra, Options)
with an empty Extra
or Options
.
See also: update/5.
update(StoreId, PathPattern, Data, Extra, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the node to create or
modify.
Data
: the Erlang term or function to store, or a khepri_payload:payload()
structure.
Extra
: extra options such as keep_while
conditions.
Options
: command options such as the command type.
returns: in the case of a synchronous put, an {ok, Result}
tuple with a
map with one entry, or an {error, Reason}
tuple; in the case of an
asynchronous put, always ok
(the actual return value may be sent by a
message if a correlation ID was specified).
Updates a specific tree node in the tree structure only if it already exists.
Internally, thePathPattern
is modified to include an
#if_node_exists{exists = true}
condition on its last component.
Otherwise, the behavior is that of put/5
.
See also: put/5.
compare_and_swap(PathPattern, DataPattern, Data) -> Result
PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | data() | function()
Result = result()
Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern
.
compare_and_swap(StoreId,
PathPattern, DataPattern, Data)
with the default store ID.
See also: compare_and_swap/4.
compare_and_swap(StoreId, PathPattern, DataPattern, Data) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | data() | function()
Result = result()
Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern
.
compare_and_swap(StoreId,
PathPattern, DataPattern, Data, #{}, #{})
.
See also: compare_and_swap/6.
compare_and_swap(StoreId, PathPattern, DataPattern, Data, Extra::Extra | Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern
.
compare_and_swap(StoreId,
PathPattern, DataPattern, Data, Extra, Options)
with an empty Extra
or
Options
.
See also: compare_and_swap/6.
compare_and_swap(StoreId, PathPattern, DataPattern, Data, Extra, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the node to create or
modify.
Data
: the Erlang term or function to store, or a khepri_payload:payload()
structure.
Extra
: extra options such as keep_while
conditions.
Options
: command options such as the command type.
returns: in the case of a synchronous put, an {ok, Result}
tuple with a
map with one entry, or an {error, Reason}
tuple; in the case of an
asynchronous put, always ok
(the actual return value may be sent by a
message if a correlation ID was specified).
Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern
.
PathPattern
is modified to include an
#if_data_matches{pattern = DataPattern}
condition on its last component.
Otherwise, the behavior is that of put/5
.
See also: put/5.
clear_payload(PathPattern) -> Result
PathPattern = khepri_path:pattern()
Result = result()
Clears the payload of a specific tree node in the tree structure.
Calling this function is the same as callingclear_payload(StoreId,
PathPattern)
with the default store ID.
See also: clear_payload/2.
clear_payload(StoreId, PathPattern) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Result = result()
Clears the payload of a specific tree node in the tree structure.
Calling this function is the same as callingclear_payload(StoreId,
PathPattern, #{}, #{})
.
See also: clear_payload/4.
clear_payload(StoreId, PathPattern, Extra::Extra | Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
Clears the payload of a specific tree node in the tree structure.
Calling this function is the same as callingclear_payload(StoreId,
PathPattern, Extra, Options)
with an empty Extra
or Options
.
See also: clear_payload/4.
clear_payload(StoreId, PathPattern, Extra, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the node to create or
modify.
Extra
: extra options such as keep_while
conditions.
Options
: command options such as the command type.
returns: in the case of a synchronous put, an {ok, Result}
tuple with a
map with one entry, or an {error, Reason}
tuple; in the case of an
asynchronous put, always ok
(the actual return value may be sent by a
message if a correlation ID was specified).
Clears the payload of a specific tree node in the tree structure.
In other words, the payload is set tokhepri_payload:no_payload()
.
Otherwise, the behavior is that of put/5
.
See also: put/5.
delete(PathPattern) -> Result
PathPattern = khepri_path:pattern()
Result = result()
Deletes all tree nodes matching the path pattern.
Calling this function is the same as callingdelete(StoreId, PathPattern)
with the default store ID.
See also: delete/2.
delete(StoreId, PathPattern) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Result = result()
delete(PathPattern, Options) -> Result
PathPattern = khepri_path:pattern()
Options = command_options()
Result = result()
Deletes all tree nodes matching the path pattern.
This function accepts the following two forms:delete(StoreId, PathPattern)
. Calling it is the same as calling
delete(StoreId, PathPattern, #{})
.delete(PathPattern, Options)
. Calling it is the same as calling
delete(StoreId, PathPattern, Options)
with the default store ID.See also: delete/3.
delete(StoreId, PathPattern, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = command_options()
Result = result() | NoRetIfAsync
NoRetIfAsync = ok
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to delete.
Options
: command options such as the command type.
returns: in the case of a synchronous delete, an {ok, Result}
tuple with
a map with zero, one or more entries, or an {error, Reason}
tuple; in the
case of an asynchronous put, always ok
(the actual return value may be
sent by a message if a correlation ID was specified).
Deletes all tree nodes matching the path pattern.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
The returned structure in the "ok" tuple will have a key corresponding to the path for each deleted node. Each key will point to a map containing the properties and payload of that deleted node.
Example:%% Delete the node at `/:foo/:bar'.
Result = khepri:delete(StoreId, [foo, bar]),
%% Here is the content of `Result'.
{ok, #{[foo, bar] => #{data => new_value,
payload_version => 2,
child_list_version => 1,
child_list_length => 0}}} = Result.
exists(PathPattern) -> Exists
PathPattern = khepri_path:pattern()
Exists = boolean()
Returns true
if the tree node pointed to by the given path exists,
otherwise false
.
exists(StoreId, PathPattern)
with the default store ID.
See also: exists/2.
exists(StoreId, PathPattern) -> Exists
StoreId = store_id()
PathPattern = khepri_path:pattern()
Exists = boolean()
exists(PathPattern, Options) -> Exists
PathPattern = khepri_path:pattern()
Options = query_options()
Exists = boolean()
Returns true
if the tree node pointed to by the given path exists,
otherwise false
.
exists(StoreId, PathPattern)
. Calling it is the same as calling
exists(StoreId, PathPattern, #{})
.exists(PathPattern, Options)
. Calling it is the same as calling
exists(StoreId, PathPattern, Options)
with the default store ID.See also: exists/3.
exists(StoreId, PathPattern, Options) -> Exists
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = query_options()
Exists = boolean()
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to check.
Options
: query options such as favor
.
returns: true
if tree the node exists, false
if it does not exist or if
there was any error.
Returns true
if the tree node pointed to by the given path exists,
otherwise false
.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
PathPattern
must point to a specific tree node and can't match
multiple nodes.
See also: get/3.
get(PathPattern) -> Result
PathPattern = khepri_path:pattern()
Result = result()
Returns all tree nodes matching the path pattern.
Calling this function is the same as callingget(StoreId, PathPattern)
with the default store ID.
See also: get/2.
get(StoreId, PathPattern) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Result = result()
get(PathPattern, Options) -> Result
PathPattern = khepri_path:pattern()
Options = query_options()
Result = result()
Returns all tree nodes matching the path pattern.
This function accepts the following two forms:get(StoreId, PathPattern)
. Calling it is the same as calling
get(StoreId, PathPattern, #{})
.get(PathPattern, Options)
. Calling it is the same as calling
get(StoreId, PathPattern, Options)
with the default store ID.See also: get/3.
get(StoreId, PathPattern, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = query_options()
Result = result()
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to get.
Options
: query options such as favor
.
returns: an {ok, Result}
tuple with a map with zero, one or more entries,
or an {error, Reason}
tuple.
Returns all tree nodes matching the path pattern.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
The returned structure in the "ok" tuple will have a key corresponding to the path for each node matching the path pattern. Each key will point to a map containing the properties and payload of that matching node.
The root node may or may not be included in the result. Currently, the root node is only included if the path pattern is one of the following:"/*"
or [?STAR]
"/**"
or [?STAR_STAR]
%% Query the node at `/:foo/:bar'.
Result = khepri:get(StoreId, [foo, bar]),
%% Here is the content of `Result'.
{ok, #{[foo, bar] => #{data => new_value,
payload_version => 2,
child_list_version => 1,
child_list_length => 0}}} = Result.
get_node_props(PathPattern) -> NodeProps
PathPattern = khepri_path:pattern()
NodeProps = node_props()
Returns the tree node properties associated with the given node path.
Calling this function is the same as callingget_node_props(StoreId,
PathPattern)
with the default store ID.
See also: get_node_props/2.
get_node_props(StoreId, PathPattern) -> NodeProps
StoreId = store_id()
PathPattern = khepri_path:pattern()
NodeProps = node_props()
get_node_props(PathPattern, Options) -> NodeProps
PathPattern = khepri_path:pattern()
Options = query_options()
NodeProps = node_props()
Returns the tree node properties associated with the given node path.
This function accepts the following two forms:get_node_props(StoreId, PathPattern)
. Calling it is the same as
calling get_node_props(StoreId, PathPattern, #{})
.get_node_props(PathPattern, Options)
. Calling it is the same as
calling get_node_props(StoreId, PathPattern, Options)
with the default
store ID.See also: get_node_props/3.
get_node_props(StoreId, PathPattern, Options) -> NodeProps
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = query_options()
NodeProps = node_props()
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to check.
Options
: query options such as favor
.
returns: the tree node properties if the node exists, or throws an exception otherwise.
Returns the tree node properties associated with the given node path.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
The PathPattern
must point to a specific tree node and can't match
multiple nodes.
get/3
, this function is optimistic and returns the
properties directly. If the node does not exist or if there are any errors,
an exception is raised.
See also: get/3.
has_data(PathPattern) -> HasData
PathPattern = khepri_path:pattern()
HasData = boolean()
Returns true
if the tree node pointed to by the given path has data,
otherwise false
.
has_data(StoreId,
PathPattern)
with the default store ID.
See also: has_data/2.
has_data(StoreId, PathPattern) -> HasData
StoreId = store_id()
PathPattern = khepri_path:pattern()
HasData = boolean()
has_data(PathPattern, Options) -> HasData
PathPattern = khepri_path:pattern()
Options = query_options()
HasData = boolean()
Returns true
if the tree node pointed to by the given path has data,
otherwise false
.
has_data(StoreId, PathPattern)
. Calling it is the same as calling
has_data(StoreId, PathPattern, #{})
.has_data(PathPattern, Options)
. Calling it is the same as calling
has_data(StoreId, PathPattern, Options)
with the default store ID.See also: has_data/3.
has_data(StoreId, PathPattern, Options) -> HasData
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = query_options()
HasData = boolean()
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to check.
Options
: query options such as favor
.
returns: true
if tree the node holds data, false
if it does not exist,
has no payload, holds a stored procedure or if there was any error.
Returns true
if the tree node pointed to by the given path has data,
otherwise false
.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
PathPattern
must point to a specific tree node and can't match
multiple nodes.
See also: get/3.
get_data(PathPattern) -> Data
PathPattern = khepri_path:pattern()
Data = data()
Returns the data associated with the given node path.
Calling this function is the same as callingget_data(StoreId,
PathPattern)
with the default store ID.
See also: get_data/2.
get_data(StoreId, PathPattern) -> Data
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = data()
get_data(PathPattern, Options) -> Data
PathPattern = khepri_path:pattern()
Options = query_options()
Data = data()
Returns the data associated with the given node path.
This function accepts the following two forms:get_data(StoreId, PathPattern)
. Calling it is the same as calling
get_data(StoreId, PathPattern, #{})
.get_data(PathPattern, Options)
. Calling it is the same as calling
get_data(StoreId, PathPattern, Options)
with the default store ID.See also: get_data/3.
get_data(StoreId, PathPattern, Options) -> Data
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = query_options()
Data = data()
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to check.
Options
: query options such as favor
.
returns: the data if the node has a data payload, or throws an exception if it does not exist, has no payload or holds a stored procedure.
Returns the data associated with the given node path.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
The PathPattern
must point to a specific tree node and can't match
multiple nodes.
get/3
, this function is optimistic and returns the data
directly. An exception is raised for the following reasons:
See also: get/3.
get_data_or(PathPattern, Default) -> Data
PathPattern = khepri_path:pattern()
Default = data()
Data = data()
Returns the data associated with the given node path, or Default
if
there is no data.
get_data_or(StoreId,
PathPattern, Default)
with the default store ID.
See also: get_data_or/3.
get_data_or(StoreId, PathPattern, Default) -> Data
StoreId = store_id()
PathPattern = khepri_path:pattern()
Default = data()
Data = data()
get_data_or(PathPattern, Default, Options) -> Data
PathPattern = khepri_path:pattern()
Default = data()
Options = query_options()
Data = data()
Returns the data associated with the given node path, or Default
if
there is no data.
get_data_or(StoreId, PathPattern, Default)
. Calling it is the same as
calling get_data_or(StoreId, PathPattern, Default, #{})
.get_data_or(PathPattern, Default, Options)
. Calling it is the same as
calling get_data_or(StoreId, PathPattern, Default, Options)
with the
default store ID.See also: get_data_or/4.
get_data_or(StoreId, PathPattern, Default, Options) -> Data
StoreId = store_id()
PathPattern = khepri_path:pattern()
Default = data()
Options = query_options()
Data = data()
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to check.
Default
: the default term to return if there is no data.
Options
: query options such as favor
.
returns: the data if the node has a data payload, or Default
if it does
not exist, has no payload or holds a stored procedure.
Returns the data associated with the given node path, or Default
if
there is no data.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
The PathPattern
must point to a specific tree node and can't match
multiple nodes.
Default
is returned if one of the following reasons is met:
See also: get/3.
has_sproc(PathPattern) -> HasStoredProc
PathPattern = khepri_path:pattern()
HasStoredProc = boolean()
Returns true
if the tree node pointed to by the given path holds a
stored procedure, otherwise false
.
has_sproc(StoreId,
PathPattern)
with the default store ID.
See also: has_sproc/2.
has_sproc(StoreId, PathPattern) -> HasStoredProc
StoreId = store_id()
PathPattern = khepri_path:pattern()
HasStoredProc = boolean()
has_sproc(PathPattern, Options) -> HasStoredProc
PathPattern = khepri_path:pattern()
Options = query_options()
HasStoredProc = boolean()
Returns true
if the tree node pointed to by the given path holds a
stored procedure, otherwise false
.
has_sproc(StoreId, PathPattern)
. Calling it is the same as calling
has_sproc(StoreId, PathPattern, #{})
.has_sproc(PathPattern, Options)
. Calling it is the same as calling
has_sproc(StoreId, PathPattern, Options)
with the default store ID.See also: has_sproc/3.
has_sproc(StoreId, PathPattern, Options) -> HasStoredProc
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = query_options()
HasStoredProc = boolean()
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to check.
Options
: query options such as favor
.
returns: true
if the node holds a stored procedure, false
if it does
not exist, has no payload, holds data or if there was any error.
Returns true
if the tree node pointed to by the given path holds a
stored procedure, otherwise false
.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
PathPattern
must point to a specific tree node and can't match
multiple nodes.
See also: get/3.
run_sproc(PathPattern, Args) -> Result
PathPattern = khepri_path:pattern()
Args = list()
Result = 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 also: run_sproc/3.
run_sproc(StoreId, PathPattern, Args) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Args = list()
Result = any()
run_sproc(PathPattern, Args, Options) -> Result
PathPattern = khepri_path:pattern()
Args = list()
Options = query_options()
Result = 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
calling run_sproc(StoreId, PathPattern, Args, #{})
.run_sproc(PathPattern, Args, Options)
. Calling it is the same as
calling run_sproc(StoreId, PathPattern, Args, Options)
with the default
store ID.See also: run_sproc/3.
run_sproc(StoreId, PathPattern, Args, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Args = list()
Options = query_options()
Result = any()
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to check.
Args
: the list of args to pass to the stored procedure; its length
must be equal to the stored procedure arity.
Options
: query options such as favor
.
returns: the result of the stored procedure execution, or throws an exception if the node does not exist, does not hold a stored procedure or if there was an error.
Runs the stored procedure pointed to by the given path and returns the result.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
The PathPattern
must point to a specific tree node and can't match
multiple nodes.
Args
list must match the number of arguments expected by the stored
procedure.
count(PathPattern) -> Result
PathPattern = khepri_path:pattern()
Result = ok(integer()) | error()
Counts all tree nodes matching the path pattern.
Calling this function is the same as callingcount(StoreId, PathPattern)
with the default store ID.
See also: count/2.
count(StoreId, PathPattern) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Result = ok(integer()) | error()
count(PathPattern, Options) -> Result
PathPattern = khepri_path:pattern()
Options = query_options()
Result = ok(integer()) | error()
Counts all tree nodes matching the path pattern.
This function accepts the following two forms:count(StoreId, PathPattern)
. Calling it is the same as calling
count(StoreId, PathPattern, #{})
.count(PathPattern, Options)
. Calling it is the same as calling
count(StoreId, PathPattern, Options)
with the default store ID.See also: count/3.
count(StoreId, PathPattern, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = query_options()
Result = ok(integer()) | error()
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to count.
Options
: query options such as favor
.
returns: an {ok, Count}
tuple with the number of matching tree nodes, or
an {error, Reason}
tuple.
Counts all tree nodes matching the path pattern.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
The root node is not included in the count.
It is implemented like get/3
. Therefore, it is not faster. It will
consume less memory though, as the result map is not constructed.
%% Query the node at `/:foo/:bar'.
Result = khepri:count(StoreId, [foo, ?STAR]),
%% Here is the content of `Result'.
{ok, 3} = Result.
register_trigger(TriggerId, EventFilter, StoredProcPath) -> Ret
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 also: register_trigger/4.
register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath) -> Ret
StoreId = khepri:store_id()
TriggerId = trigger_id()
EventFilter = khepri_evf:event_filter() | khepri_path:pattern()
StoredProcPath = khepri_path:path()
Ret = ok | error()
register_trigger(TriggerId, EventFilter, StoredProcPath, Options) -> Ret
TriggerId = trigger_id()
EventFilter = khepri_evf:event_filter() | khepri_path:pattern()
StoredProcPath = khepri_path:path()
Options = command_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 calling register_trigger(StoreId, TriggerId,
EventFilter, StoredProcPath, #{})
.register_trigger(TriggerId, EventFilter, StoredProcPath, Options)
.
Calling it is the same as calling register_trigger(StoreId, TriggerId,
EventFilter, StoredProcPath, Options)
with the default store ID.See also: register_trigger/5.
register_trigger(StoreId, TriggerId, EventFilter, StoredProcPath, Options) -> Ret
StoreId = khepri:store_id()
TriggerId = trigger_id()
EventFilter = khepri_evf:event_filter() | khepri_path:pattern()
StoredProcPath = khepri_path:path()
Options = command_options()
Ret = ok | error()
StoreId
: the name of the Khepri store.
TriggerId
: the name of the trigger.
EventFilter
: the event filter used to associate an event with a
stored procedure.
StoredProcPath
: the path to the stored procedure to execute when the
corresponding event occurs.
returns: ok
if the trigger was registered, an {error, Reason}
tuple
otherwise.
Registers a trigger.
A trigger is based on an event filter. It associates an event with a stored procedure. When an event matching the event filter is emitted, the stored procedure is executed.
The following event filters are documented by khepri_evf:event_filter()
.
Here are examples of event filters:
%% An event filter can be explicitly created using the `khepri_evf'
%% module. This is possible to specify properties at the same time.
EventFilter = khepri_evf:tree([stock, wood, <<"oak">>], %% Required
#{on_actions => [delete], %% Optional
priority => 10}). %% Optional
%% For ease of use, some terms can be automatically converted to an event
%% filter. In this example, a Unix-like path can be used as a tree event
%% filter.
EventFilter = "/:stock/:wood/oak".
The stored procedure is expected to accept a single argument. This argument is a map containing the event properties. Here is an example:
my_stored_procedure(Props) ->
#{path := Path},
on_action => Action} = Props.
The stored procedure is executed on the leader's Erlang node.
It is guaranteed to run at least once. It could be executed multiple times if the Ra leader changes, therefore the stored procedure must be idempotent.list(PathPattern) -> Result
PathPattern = khepri_path:pattern()
Result = result()
Returns all direct child nodes under the given path.
Calling this function is the same as callinglist(StoreId, PathPattern)
with the default store ID.
See also: list/2.
list(StoreId, PathPattern) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Result = result()
list(PathPattern, Options) -> Result
PathPattern = khepri_path:pattern()
Options = query_options()
Result = result()
Returns all direct child nodes under the given path.
This function accepts the following two forms:list(StoreId, PathPattern)
. Calling it is the same as calling
list(StoreId, PathPattern, #{})
.list(PathPattern, Options)
. Calling it is the same as calling
list(StoreId, PathPattern, Options)
with the default store ID.See also: list/3.
list(StoreId, PathPattern, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = query_options()
Result = result()
StoreId
: the name of the Khepri store.
PathPattern
: the path (or path pattern) to the nodes to get.
Options
: query options such as favor
.
returns: an {ok, Result}
tuple with a map with zero, one or more entries,
or an {error, Reason}
tuple.
Returns all direct child nodes under the given path.
The PathPattern
can be provided as native path (a list of node names and
conditions) or as a string. See khepri_path:from_string/1
.
#if_name_matches{regex = any}
condition is appended to the
PathPattern
. Otherwise, the behavior is that of get/3
.
See also: get/3.
find(PathPattern, Condition) -> Result
PathPattern = khepri_path:pattern()
Condition = khepri_path:pattern_component()
Result = result()
Returns all tree nodes matching the path pattern.
Calling this function is the same as callingfind(StoreId, PathPattern)
with the default store ID.
See also: find/3.
find(StoreId, PathPattern, Condition) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Condition = khepri_path:pattern_component()
Result = result()
find(PathPattern, Condition, Options) -> Result
PathPattern = khepri_path:pattern()
Condition = khepri_path:pattern_component()
Options = query_options()
Result = result()
Returns all tree nodes matching the path pattern.
This function accepts the following two forms:find(StoreId, PathPattern, Condition)
. Calling it is the same as
calling find(StoreId, PathPattern, Condition, #{})
.find(PathPattern, Condition, Options)
. Calling it is the same as
calling find(StoreId, PathPattern, Condition, Options)
with the default
store ID.See also: find/4.
find(StoreId, PathPattern, Condition, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Condition = khepri_path:pattern_component()
Options = query_options()
Result = result()
StoreId
: the name of the Khepri store.
PathPattern
: the path indicating where to start the search from.
Condition
: the condition nodes must match to be part of the result.
returns: an {ok, Result}
tuple with a map with zero, one or more entries,
or an {error, Reason}
tuple.
Finds tree nodes under PathPattern
which match the given Condition
.
The PathPattern
can be provided as a list of node names and conditions or
as a string. See khepri_path:from_string/1
.
Nodes are searched deeply under the given PathPattern
, not only among
direct child nodes.
%% Find nodes with data under `/:foo/:bar'.
Result = khepri:find(
StoreId,
[foo, bar],
#if_has_data{has_data = true}),
%% Here is the content of `Result'.
{ok, #{[foo, bar, baz] => #{data => baz_value,
payload_version => 2,
child_list_version => 1,
child_list_length => 0},
[foo, bar, deep, under, qux] => #{data => qux_value,
payload_version => 1,
child_list_version => 1,
child_list_length => 0}}} = Result.
transaction(Fun) -> Ret
Fun = khepri_tx:tx_fun()
Ret = Atomic | Aborted
Atomic = {atomic, khepri_tx:tx_fun_result()}
Aborted = khepri_tx:tx_abort()
Runs a transaction and returns its result.
Calling this function is the same as callingtransaction(StoreId, Fun)
with the default store ID.
See also: transaction/2.
transaction(StoreId, Fun) -> Ret
StoreId = store_id()
Fun = khepri_tx:tx_fun()
Ret = Atomic | Aborted
Atomic = {atomic, khepri_tx:tx_fun_result()}
Aborted = khepri_tx:tx_abort()
transaction(Fun, ReadWriteOrOptions) -> Ret
Fun = khepri_tx:tx_fun()
ReadWriteOrOptions = ReadWrite | Options
ReadWrite = ro | rw | auto
Options = command_options() | query_options()
Ret = Atomic | Aborted | NoRetIfAsync
Atomic = {atomic, khepri_tx:tx_fun_result()}
Aborted = khepri_tx:tx_abort()
NoRetIfAsync = ok
Runs a transaction and returns its result.
This function accepts the following two forms:transaction(StoreId, Fun)
. Calling it is the same as calling
transaction(StoreId, Fun, #{})
.transaction(Fun, Options)
. Calling it is the same as calling
transaction(StoreId, Fun, Options)
with the default store ID.See also: transaction/3.
transaction(StoreId, Fun, ReadWrite) -> Ret
StoreId = store_id()
Fun = khepri_tx:tx_fun()
ReadWrite = ro | rw | auto
Ret = Atomic | Aborted
Atomic = {atomic, khepri_tx:tx_fun_result()}
Aborted = khepri_tx:tx_abort()
transaction(StoreId, Fun, Options) -> Ret
StoreId = store_id()
Fun = khepri_tx:tx_fun()
Options = command_options() | query_options()
Ret = Atomic | Aborted | NoRetIfAsync
Atomic = {atomic, khepri_tx:tx_fun_result()}
Aborted = khepri_tx:tx_abort()
NoRetIfAsync = ok
transaction(Fun, ReadWrite, Options) -> Ret
Fun = khepri_tx:tx_fun()
ReadWrite = ro | rw | auto
Options = command_options() | query_options()
Ret = Atomic | Aborted | NoRetIfAsync
Atomic = {atomic, khepri_tx:tx_fun_result()}
Aborted = khepri_tx:tx_abort()
NoRetIfAsync = ok
Runs a transaction and returns its result.
This function accepts the following three forms:transaction(StoreId, PathPattern, ReadWrite)
. Calling it is the same
as calling transaction(StoreId, PathPattern, ReadWrite, #{})
.transaction(StoreId, PathPattern, Options)
. Calling it is the same
as calling transaction(StoreId, PathPattern, auto, Options)
.transaction(PathPattern, ReadWrite, Options)
. Calling it is the same
as calling transaction(StoreId, PathPattern, ReadWrite, Options)
with the
default store ID.See also: transaction/4.
transaction(StoreId, Fun, ReadWrite, Options) -> Ret
StoreId = store_id()
Fun = khepri_tx:tx_fun()
ReadWrite = ro | rw | auto
Options = command_options() | query_options()
Ret = Atomic | Aborted | NoRetIfAsync
Atomic = {atomic, khepri_tx:tx_fun_result()}
Aborted = khepri_tx:tx_abort()
NoRetIfAsync = ok
StoreId
: the name of the Khepri store.
Fun
: an arbitrary anonymous function.
ReadWrite
: the read/write or read-only nature of the transaction.
Options
: command options such as the command type.
returns: in the case of a synchronous transaction, {atomic, Result}
where
Result
is the return value of Fun
, or {aborted, Reason}
if the
anonymous function was aborted; in the case of an asynchronous transaction,
always ok
(the actual return value may be sent by a message if a
correlation ID was specified).
Runs a transaction and returns its result.
Fun
is an arbitrary anonymous function which takes no arguments.
The ReadWrite
flag determines what the anonymous function is allowed to
do and in which context it runs:
ReadWrite
is ro
, Fun
can do whatever it wants, except modify
the content of the store. In other words, uses of khepri_tx:put/2
or khepri_tx:delete/1
are forbidden and will abort the function.
Fun
is executed from a process on the leader Ra member.ReadWrite
is rw
, Fun
can use the khepri_tx
transaction
API as well as any calls to other modules as long as those functions or what
they do is permitted. See khepri_tx
for more details. If Fun
does
or calls something forbidden, the transaction will be aborted. Fun
is
executed in the context of the state machine process on each Ra
members.ReadWrite
is auto
, Fun
is analyzed to determine if it calls
khepri_tx:put/2
or khepri_tx:delete/1
, or uses any denied
operations for a read/write transaction. If it does, this is the same as
setting ReadWrite
to true. Otherwise, this is the equivalent of setting
ReadWrite
to false.Options
is relevant for both read-only and read-write transactions
(including audetected ones). However note that both types expect different
options.
Fun
can be any term. That result is returned in an
{atomic, Result}
tuple if the transaction is synchronous. The result is
sent by message if the transaction is asynchronous and a correlation ID was
specified.
clear_store() -> Result
Result = result()
Wipes out the entire tree.
Calling this function is the same as callingclear_store(StoreId)
with
the default store ID.
See also: clear_store/1.
clear_store(StoreId) -> Result
StoreId = store_id()
Result = result()
clear_store(Options) -> Result
Options = command_options()
Result = result()
Wipes out the entire tree.
This function accepts the following two forms:clear_store(StoreId)
. Calling it is the same as calling
clear_store(StoreId, #{})
.clear_store(Options)
. Calling it is the same as calling
clear_store(StoreId, Options)
with the default store ID.See also: clear_store/2.
clear_store(StoreId, Options) -> Result
StoreId = store_id()
Options = command_options()
Result = result()
StoreId
: the name of the Khepri store.
Options
: command options such as the command type.
returns: in the case of a synchronous delete, an {ok, Result}
tuple with
a map with zero, one or more entries, or an {error, Reason}
tuple; in the
case of an asynchronous put, always ok
(the actual return value may be
sent by a message if a correlation ID was specified).
Wipes out the entire tree.
Note that the root node will remain unmodified however.See also: delete/3.
'put!'(PathPattern, Data) -> NodePropsMap
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
NodePropsMap = node_props_map()
Creates or modifies a specific tree node in the tree structure.
Calling this function is the same as callingput/2
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: put/2.
'put!'(StoreId, PathPattern, Data) -> NodePropsMap
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
NodePropsMap = node_props_map()
Creates or modifies a specific tree node in the tree structure.
Calling this function is the same as callingput/3
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: put/3.
'put!'(StoreId, PathPattern, Data, ExtraOrOptions::Extra | Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = NodePropsMap | NoRetIfAsync
NodePropsMap = node_props_map()
NoRetIfAsync = ok
Creates or modifies a specific tree node in the tree structure.
Calling this function is the same as callingput/4
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: put/4.
'put!'(StoreId, PathPattern, Data, Extra, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = NodePropsMap | NoRetIfAsync
NodePropsMap = node_props_map()
NoRetIfAsync = ok
Creates or modifies a specific tree node in the tree structure.
Calling this function is the same as callingput/5
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: put/5.
'create!'(PathPattern, Data) -> NodePropsMap
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
NodePropsMap = node_props_map()
Creates a specific tree node in the tree structure only if it does not exist.
Calling this function is the same as callingcreate/2
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: create/2.
'create!'(StoreId, PathPattern, Data) -> NodePropsMap
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
NodePropsMap = node_props_map()
Creates a specific tree node in the tree structure only if it does not exist.
Calling this function is the same as callingcreate/3
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: create/3.
'create!'(StoreId, PathPattern, Data, ExtraOrOptions::Extra | Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = NodePropsMap | NoRetIfAsync
NodePropsMap = node_props_map()
NoRetIfAsync = ok
Creates a specific tree node in the tree structure only if it does not exist.
Calling this function is the same as callingcreate/4
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: create/4.
'create!'(StoreId, PathPattern, Data, Extra, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = NodePropsMap | NoRetIfAsync
NodePropsMap = node_props_map()
NoRetIfAsync = ok
Creates a specific tree node in the tree structure only if it does not exist.
Calling this function is the same as callingcreate/5
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: create/5.
'update!'(PathPattern, Data) -> NodePropsMap
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
NodePropsMap = node_props_map()
Updates a specific tree node in the tree structure only if it already exists.
Calling this function is the same as callingupdate/2
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: update/2.
'update!'(StoreId, PathPattern, Data) -> NodePropsMap
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
NodePropsMap = node_props_map()
Updates a specific tree node in the tree structure only if it already exists.
Calling this function is the same as callingupdate/3
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: update/3.
'update!'(StoreId, PathPattern, Data, ExtraOrOptions::Extra | Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = NodePropsMap | NoRetIfAsync
NodePropsMap = node_props_map()
NoRetIfAsync = ok
Updates a specific tree node in the tree structure only if it already exists.
Calling this function is the same as callingupdate/4
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: update/4.
'update!'(StoreId, PathPattern, Data, Extra, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = NodePropsMap | NoRetIfAsync
NodePropsMap = node_props_map()
NoRetIfAsync = ok
Updates a specific tree node in the tree structure only if it already exists.
Calling this function is the same as callingupdate/5
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. If
there is an error, an exception is thrown.
See also: update/5.
'compare_and_swap!'(PathPattern, DataPattern, Data) -> NodePropsMap
PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | data() | function()
NodePropsMap = node_props_map()
Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern
.
compare_and_swap/3
but
the result is unwrapped (from the {ok, Result}
tuple) and returned
directly. If there is an error, an exception is thrown.
See also: compare_and_swap/3.
'compare_and_swap!'(StoreId, PathPattern, DataPattern, Data) -> NodePropsMap
StoreId = store_id()
PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | data() | function()
NodePropsMap = node_props_map()
Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern
.
compare_and_swap/4
but
the result is unwrapped (from the {ok, Result}
tuple) and returned
directly. If there is an error, an exception is thrown.
See also: compare_and_swap/4.
'compare_and_swap!'(StoreId, PathPattern, DataPattern, Data, ExtraOrOptions::Extra | Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = NodePropsMap | NoRetIfAsync
NodePropsMap = node_props_map()
NoRetIfAsync = ok
Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern
.
compare_and_swap/5
but
the result is unwrapped (from the {ok, Result}
tuple) and returned
directly. If there is an error, an exception is thrown.
See also: compare_and_swap/5.
'compare_and_swap!'(StoreId, PathPattern, DataPattern, Data, Extra, Options) -> Result
StoreId = store_id()
PathPattern = khepri_path:pattern()
DataPattern = ets:match_pattern()
Data = khepri_payload:payload() | data() | function()
Extra = #{keep_while => khepri_condition:keep_while()}
Options = command_options()
Result = NodePropsMap | NoRetIfAsync
NodePropsMap = node_props_map()
NoRetIfAsync = ok
Updates a specific tree node in the tree structure only if it already
exists and its data matches the given DataPattern
.
compare_and_swap/6
but
the result is unwrapped (from the {ok, Result}
tuple) and returned
directly. If there is an error, an exception is thrown.
See also: compare_and_swap/6.
'get!'(PathPattern) -> NodePropsMap
PathPattern = khepri_path:pattern()
NodePropsMap = node_props_map()
Returns all tree nodes matching the path pattern.
Calling this function is the same as callingget/1
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. It
closer to Elixir conventions in pipelines however.
See also: get/1.
'get!'(StoreId, PathPattern) -> NodePropsMap
StoreId = store_id()
PathPattern = khepri_path:pattern()
NodePropsMap = node_props_map()
'get!'(PathPattern, Options) -> NodePropsMap
PathPattern = khepri_path:pattern()
Options = query_options()
NodePropsMap = node_props_map()
Returns all tree nodes matching the path pattern.
Calling this function is the same as callingget/2
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. It
closer to Elixir conventions in pipelines however.
See also: get/2.
'get!'(StoreId, PathPattern, Options) -> NodePropsMap
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = query_options()
NodePropsMap = node_props_map()
Returns all tree nodes matching the path pattern.
Calling this function is the same as callingget/3
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. It
closer to Elixir conventions in pipelines however.
See also: get/3.
'delete!'(PathPattern) -> NodePropsMap
PathPattern = khepri_path:pattern()
NodePropsMap = node_props_map()
Deletes all tree nodes matching the path pattern.
Calling this function is the same as callingdelete/1
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. It
closer to Elixir conventions in pipelines however.
See also: delete/1.
'delete!'(StoreId, PathPattern) -> NodePropsMap
StoreId = store_id()
PathPattern = khepri_path:pattern()
NodePropsMap = node_props_map()
'delete!'(PathPattern, Options) -> NodePropsMap
PathPattern = khepri_path:pattern()
Options = query_options()
NodePropsMap = node_props_map()
Deletes all tree nodes matching the path pattern.
Calling this function is the same as callingdelete/2
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. It
closer to Elixir conventions in pipelines however.
See also: delete/2.
'delete!'(StoreId, PathPattern, Options) -> NodePropsMap
StoreId = store_id()
PathPattern = khepri_path:pattern()
Options = query_options()
NodePropsMap = node_props_map()
Deletes all tree nodes matching the path pattern.
Calling this function is the same as callingdelete/3
but the result
is unwrapped (from the {ok, Result}
tuple) and returned directly. It
closer to Elixir conventions in pipelines however.
See also: delete/3.
info() -> ok
Lists the running stores on stdout.
info(StoreId) -> ok
StoreId = store_id()
StoreId
: the name of the Khepri store.
Lists the content of specified store on stdout.
info(StoreId, Options) -> ok
StoreId = store_id()
Options = query_options()
StoreId
: the name of the Khepri store.
Lists the content of specified store on stdout.
Generated by EDoc