khepri_adv (khepri v0.6.0)

Khepri database advanced API.

This module exposes variants of the functions in khepri which return more detailed return values for advanced use cases. Here are some examples of what can be achieved with this module:

Distinguish a tree node with the undefined atom as its payload, from a tree node with no payload, from a non-existing tree node.
Know the payload version after a call to the functions based on put/4 which can be useful to perform transactional operations without using khepri:transaction/4.

Functions provided by khepri are implemented on top of this module and simplify the return value for the more common use cases.

Link to this section Summary

Types

many_results/0

Return value of a query or synchronous command targeting many tree nodes.

node_props_map/0

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

single_result/0

Return value of a query or synchronous command targeting one specific tree node.

Functions

clear_many_payloads(PathPattern)

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

clear_many_payloads(StoreId, PathPattern)

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

clear_many_payloads(StoreId, PathPattern, Options)

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

clear_payload(PathPattern)

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

clear_payload(StoreId, PathPattern)

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

clear_payload(StoreId, PathPattern, Options)

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

compare_and_swap(PathPattern, DataPattern, Data)

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

compare_and_swap(StoreId, PathPattern, DataPattern, Data)

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

compare_and_swap(StoreId, PathPattern, DataPattern, Data, Options)

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

create(PathPattern, Data)

Creates a tree node with the given payload.

create(StoreId, PathPattern, Data)

Creates a tree node with the given payload.

create(StoreId, PathPattern, Data, Options)

Creates a tree node with the given payload.

delete(PathPattern)

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

delete(StoreId, PathPattern)

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

delete(StoreId, PathPattern, Options)

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

delete_many(PathPattern)

Deletes all tree nodes matching the given path pattern.

delete_many(StoreId, PathPattern)

Deletes all tree nodes matching the given path pattern.

delete_many(StoreId, PathPattern, Options)

Deletes all tree nodes matching the given path pattern.

get(PathPattern)

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

get(StoreId, PathPattern)

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

get(StoreId, PathPattern, Options)

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

get_many(PathPattern)

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

get_many(StoreId, PathPattern)

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

get_many(StoreId, PathPattern, Options)

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

put(PathPattern, Data)

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

put(StoreId, PathPattern, Data)

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

put(StoreId, PathPattern, Data, Options)

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

put_many(PathPattern, Data)

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

put_many(StoreId, PathPattern, Data)

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

put_many(StoreId, PathPattern, Data, Options)

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

update(PathPattern, Data)

Updates an existing tree node with the given payload.

update(StoreId, PathPattern, Data)

Updates an existing tree node with the given payload.

update(StoreId, PathPattern, Data, Options)

Updates an existing tree node with the given payload.

Link to this section Types

many_results/0

-type many_results() :: khepri_machine:common_ret().

Return value of a query or synchronous command targeting many tree nodes.

node_props_map/0

-type node_props_map() :: #{khepri_path:native_path() => khepri:node_props()}.

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

single_result/0

-type single_result() :: khepri:ok(khepri:node_props() | #{}) | khepri:error().

Return value of a query or synchronous command targeting one specific tree node.

Link to this section Functions

clear_many_payloads(PathPattern)

-spec clear_many_payloads(PathPattern) -> Ret
                       when PathPattern :: khepri_path:pattern(), Ret :: khepri_adv:many_results().

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

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

clear_many_payloads(StoreId, PathPattern)

-spec clear_many_payloads(StoreId, PathPattern) -> Ret
                       when
                           StoreId :: khepri:store_id(),
                           PathPattern :: khepri_path:pattern(),
                           Ret :: khepri_adv:many_results().

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

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

See also: clear_many_payloads/3.

clear_many_payloads(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_adv:many_results() | khepri_machine:async_ret().

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

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

clear_payload(PathPattern)

-spec clear_payload(PathPattern) -> Ret
                 when PathPattern :: khepri_path:pattern(), Ret :: khepri_adv:single_result().

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

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

See also: clear_payload/2, clear_payload/3.

clear_payload(StoreId, PathPattern)

-spec clear_payload(StoreId, PathPattern) -> Ret
                 when
                     StoreId :: khepri:store_id(),
                     PathPattern :: khepri_path:pattern(),
                     Ret :: khepri_adv:single_result().

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

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

See also: clear_payload/3.

clear_payload(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_adv:single_result() | 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 to khepri_payload:no_payload(). Otherwise, the behavior is that of update/4.

See also: update/4, khepri:clear_payload/3.

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_adv:single_result().

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

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

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_adv:single_result().

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

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

See also: compare_and_swap/5.

compare_and_swap(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_adv:single_result() | 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.

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

See also: put/4, khepri:compare_and_swap/5.

create(PathPattern, Data)

-spec create(PathPattern, Data) -> Ret
          when
              PathPattern :: khepri_path:pattern(),
              Data :: khepri_payload:payload() | khepri:data() | fun(),
              Ret :: khepri_adv:single_result().

Creates a tree node with the given payload.

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

See also: create/3, create/4.

create(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_adv:single_result().

Creates a tree node with the given payload.

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

See also: create/4.

create(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_adv:single_result() | 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.

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

See also: put/4, update/4, khepri:create/4.

delete(PathPattern)

-spec delete(PathPattern) -> Ret
          when PathPattern :: khepri_path:pattern(), Ret :: khepri_adv:single_result().

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

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

See also: delete/2, delete/3.

delete(StoreId, PathPattern)

-spec delete(StoreId, PathPattern) -> Ret
          when
              StoreId :: khepri:store_id(),
              PathPattern :: khepri_path:pattern(),
              Ret :: khepri_adv:single_result();
      (PathPattern, Options) -> Ret
          when
              PathPattern :: khepri_path:pattern(),
              Options :: khepri:command_options() | khepri:tree_options(),
              Ret :: khepri_adv:single_result().

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 calling delete(StoreId, PathPattern, #{}).
delete(PathPattern, Options). Calling it is the same as calling delete(StoreId, PathPattern, Options) with the default store ID (see khepri_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_adv:single_result() | 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.

The returned {ok, NodeProps} tuple contains a map with the properties and payload (if any) of the targeted tree node as they were before the delete. If the targeted tree node didn't exist, NodeProps will be an empty map.

When doing an asynchronous update, the khepri:wait_for_async_ret/1 function can be used to receive the message from Ra.

Example:

  %% Delete the tree node at `/:foo/:bar'.
  {ok, #{data := value,
         payload_version := 1}} = khepri_adv:delete(StoreId, [foo, bar]).

See also: delete_many/3, khepri:delete/3.

delete_many(PathPattern)

-spec delete_many(PathPattern) -> Ret
               when PathPattern :: khepri_path:pattern(), Ret :: khepri_adv:many_results().

Deletes all tree nodes matching the given path pattern.

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

See also: delete_many/2, delete_many/3.

delete_many(StoreId, PathPattern)

-spec delete_many(StoreId, PathPattern) -> Ret
               when
                   StoreId :: khepri:store_id(),
                   PathPattern :: khepri_path:pattern(),
                   Ret :: khepri_adv:many_results();
           (PathPattern, Options) -> Ret
               when
                   PathPattern :: khepri_path:pattern(),
                   Options :: khepri:command_options() | khepri:tree_options(),
                   Ret :: khepri_adv:many_results().

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 calling delete(StoreId, PathPattern, #{}).
delete_many(PathPattern, Options). Calling it is the same as calling delete(StoreId, PathPattern, Options) with the default store ID (see khepri_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_adv:many_results() | 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.

The returned {ok, NodePropsMap} tuple contains a map where keys correspond to the path to a deleted tree node. Each key then points to a map containing the properties and payload (if any) of that deleted tree node as they were before the delete.

When doing an asynchronous update, the khepri:wait_for_async_ret/1 function can be used to receive the message from Ra.

Example:

  %% Delete the tree node at `/:foo/:bar'.
  {ok, #{[foo, bar] := #{data := value,
                         payload_version := 1},
         [baz, bar] := #{payload_version := 1}}} = khepri_adv:delete_many(
                                                     StoreId, [foo, bar]).

See also: delete/3, khepri:delete/3.

get(PathPattern)

-spec get(PathPattern) -> Ret
       when PathPattern :: khepri_path:pattern(), Ret :: khepri_adv:single_result().

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

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

See also: get/2, get/3.

get(StoreId, PathPattern)

-spec get(StoreId, PathPattern) -> Ret
       when
           StoreId :: khepri:store_id(),
           PathPattern :: khepri_path:pattern(),
           Ret :: khepri_adv:single_result();
   (PathPattern, Options) -> Ret
       when
           PathPattern :: khepri_path:pattern(),
           Options :: khepri:query_options() | khepri:tree_options(),
           Ret :: khepri_adv:single_result().

Returns the properties and 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 calling get(StoreId, PathPattern, #{}).
get(PathPattern, Options). Calling it is the same as calling get(StoreId, PathPattern, Options) with the default store ID (see khepri_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_adv:single_result().

Returns the properties and 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 returned {ok, NodeProps} tuple contains a map with the properties and payload (if any) of the targeted tree node. If the tree node is not found, {error, ?khepri_error(node_not_found, Info)} is returned.

Example: query a tree node which holds the atom value

  %% Query the tree node at `/:foo/:bar'.
  {ok, #{data := value,
         payload_version := 1}} = khepri_adv:get(StoreId, [foo, bar]).

Example: query an existing tree node with no payload

  %% Query the tree node at `/:no_payload'.
  {ok, #{payload_version := 1}} = khepri_adv:get(StoreId, [no_payload]).

Example: query a non-existent tree node

  %% Query the tree node at `/:non_existent'.
  {error, ?khepri_error(node_not_found, _)} = khepri_adv:get(
                                                StoreId, [non_existent]).

See also: get_many/3, khepri:get/3.

get_many(PathPattern)

-spec get_many(PathPattern) -> Ret
            when PathPattern :: khepri_path:pattern(), Ret :: khepri_adv:many_results().

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

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

See also: get_many/2, get_many/3.

get_many(StoreId, PathPattern)

-spec get_many(StoreId, PathPattern) -> Ret
            when
                StoreId :: khepri:store_id(),
                PathPattern :: khepri_path:pattern(),
                Ret :: khepri_adv:many_results();
        (PathPattern, Options) -> Ret
            when
                PathPattern :: khepri_path:pattern(),
                Options :: khepri:query_options() | khepri:tree_options(),
                Ret :: khepri_adv:many_results().

Returns properties and 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 calling get_many(StoreId, PathPattern, #{}).
get_many(PathPattern, Options). Calling it is the same as calling get_many(StoreId, PathPattern, Options) with the default store ID (see khepri_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_adv:many_results().

Returns properties and payloads 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.

Example: query all nodes in the tree

  %% Get all nodes in the tree. The tree is:
  %% <root>
  %% `-- foo
  %%     `-- bar = value
  {ok, #{[foo] :=
         #{payload_version := 1},
         [foo, bar] :=
         #{data := value,
           payload_version := 1}}} = khepri_adv:get_many(
                                       StoreId,
                                       [?KHEPRI_WILDCARD_STAR_STAR]).

See also: get/3, khepri:get_many/3.

put(PathPattern, Data)

-spec put(PathPattern, Data) -> Ret
       when
           PathPattern :: khepri_path:pattern(),
           Data :: khepri_payload:payload() | khepri:data() | fun(),
           Ret :: khepri:minimal_ret() | khepri_adv:single_result().

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

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

See also: put/3, put/4.

put(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() | khepri_adv:single_result().

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

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

See also: put/4.

put(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_adv:single_result() | 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.

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 returned {ok, NodeProps} tuple contains a map with the properties and payload (if any) of the targeted tree node: the payload was the one before the update, other properties like the payload version correspond to the updated node. If the targeted tree node didn't exist, NodeProps will be an empty map.

The payload must be one of the following form:

An explicit absence of payload (khepri_payload:no_payload()), using the marker returned by khepri_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 khepri:wait_for_async_ret/1 function can be used to receive the message from Ra.

The returned {ok, NodeProps} tuple contains a map with the properties and payload (if any) of the targeted tree node as they were before the put.

Example:

  %% Insert a tree node at `/:foo/:bar', overwriting the previous value.
  {ok, #{data := value,
         payload_version := 1}} = khepri_adv:put(
                                    StoreId, [foo, bar], new_value).

put_many(PathPattern, Data)

-spec put_many(PathPattern, Data) -> Ret
            when
                PathPattern :: khepri_path:pattern(),
                Data :: khepri_payload:payload() | khepri:data() | fun(),
                Ret :: khepri_adv:many_results().

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

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

See also: put_many/3, put_many/4.

put_many(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_adv:many_results().

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

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

See also: put_many/4.

put_many(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_adv:many_results() | 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 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 returned {ok, NodePropsMap} tuple contains a map where keys correspond to the path to a tree node matching the path pattern. Each key then points to a map containing the properties and payload (if any) of the targeted tree node: the payload was the one before the update, other properties like the payload version correspond to the updated node.

The payload must be one of the following form:

An explicit absence of payload (khepri_payload:no_payload()), using the marker returned by khepri_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 khepri:wait_for_async_ret/1 function can be used to receive the message from Ra.

Example:

  %% Set value of all tree nodes matching `/*/:bar', to `new_value'.
  {ok, #{[foo, bar] :=
         #{data := value,
           payload_version := 1},
         [baz, bar] :=
         #{payload_version := 1}}} = khepri_adv:put_many(
                                       StoreId,
                                       [?KHEPRI_WILDCARD_STAR, bar],
                                       new_value).

See also: put/4, khepri:put_many/4.

update(PathPattern, Data)

-spec update(PathPattern, Data) -> Ret
          when
              PathPattern :: khepri_path:pattern(),
              Data :: khepri_payload:payload() | khepri:data() | fun(),
              Ret :: khepri_adv:single_result().

Updates an existing tree node with the given payload.

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

See also: update/3, update/4.

update(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_adv:single_result().

Updates an existing tree node with the given payload.

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

See also: update/4.

update(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_adv:single_result() | 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.

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

See also: create/4, put/4, khepri:update/4.

Settings khepri_adv (khepri v0.6.0)

Link to this section Summary

Types

Functions

Link to this section Types

many_results/0

node_props_map/0

single_result/0

Link to this section Functions

clear_many_payloads(PathPattern)

clear_many_payloads(StoreId, PathPattern)

clear_many_payloads(StoreId, PathPattern, Options)

clear_payload(PathPattern)

clear_payload(StoreId, PathPattern)

clear_payload(StoreId, PathPattern, Options)

compare_and_swap(PathPattern, DataPattern, Data)

compare_and_swap(StoreId, PathPattern, DataPattern, Data)

compare_and_swap(StoreId, PathPattern, DataPattern, Data, Options)

create(PathPattern, Data)

create(StoreId, PathPattern, Data)

create(StoreId, PathPattern, Data, Options)

delete(PathPattern)

delete(StoreId, PathPattern)

delete(StoreId, PathPattern, Options)

delete_many(PathPattern)

delete_many(StoreId, PathPattern)

delete_many(StoreId, PathPattern, Options)

get(PathPattern)

get(StoreId, PathPattern)

get(StoreId, PathPattern, Options)

get_many(PathPattern)

get_many(StoreId, PathPattern)

get_many(StoreId, PathPattern, Options)

put(PathPattern, Data)

put(StoreId, PathPattern, Data)

put(StoreId, PathPattern, Data, Options)

put_many(PathPattern, Data)

put_many(StoreId, PathPattern, Data)

put_many(StoreId, PathPattern, Data, Options)

update(PathPattern, Data)

update(StoreId, PathPattern, Data)

update(StoreId, PathPattern, Data, Options)

khepri_adv (khepri v0.6.0)