Overview

Module khepri_adv

• Description
• Data Types
• Function Index
• Function Details

Description

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.

Data Types

many_results()

many_results() = khepri_machine:common_ret()

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

node_props_map()

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

single_result() = khepri:ok(khepri:node_props() | #{}) | khepri:error()

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

Function Index

Function Details

get/1

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

See also: get/2, get/3.

get/2

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

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

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 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 get multiple nodes at once, use get_many/3.

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.

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

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

%% 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/1

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

See also: get_many/2, get_many/3.

get_many/2

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

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

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.

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 that matching tree node.

%% 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/2

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

See also: put/3, put/4.

put/3

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

See also: put/4.

put/4

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

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

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

When using a simple path (i.e. without conditions), if the targeted tree node does not exist, it is created using the given payload. If the targeted tree node exists, it is updated with the given payload and its payload version is increased by one. Missing parent nodes are created on the way.

When using a path pattern, the behavior is the same. However if a condition in the path pattern is not met, an error is returned and the tree structure is not modified.

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

• 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 handle_async_ret/1 function should be used to handle the message received 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.

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

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

put_many/2

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

See also: put_many/3, put_many/4.

put_many/3

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

See also: put_many/4.

put_many/4

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

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

When using a simple path (i.e. without conditions), if the targeted tree node does not exist, it is created using the given payload. If the targeted tree node exists, it is updated with the given payload and its payload version is increased by one. Missing parent nodes are created on the way.

When using a path pattern, the behavior is the same. However if a condition in the path pattern is not met, an error is returned and the tree structure is not modified.

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

• 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 handle_async_ret/1 function should be used to handle the message received from Ra.

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

create/2

Creates a tree node with the given payload.

See also: create/3, create/4.

create/3

Creates a tree node with the given payload.

See also: create/4.

create/4

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.

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

update/2

Updates an existing tree node with the given payload.

See also: update/3, update/4.

update/3

Updates an existing tree node with the given payload.

See also: update/4.

update/4

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.

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

compare_and_swap/3

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

See also: compare_and_swap/4, compare_and_swap/5.

compare_and_swap/4

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

See also: compare_and_swap/5.

compare_and_swap/5

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.

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

delete/1

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

See also: delete/2, delete/3.

delete/2

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

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

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 handle_async_ret/1 function should be used to handle the message received from Ra.

%% 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/1

Deletes all tree nodes matching the given path pattern.

See also: delete_many/2, delete_many/3.

delete_many/2

Deletes all tree nodes matching the given path pattern.

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

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 handle_async_ret/1 function should be used to handle the message received from Ra.

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

clear_payload/1

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

See also: clear_payload/2, clear_payload/3.

clear_payload/2

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

See also: clear_payload/3.

clear_payload/3

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

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

clear_many_payloads/1

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

See also: clear_many_payloads/2, clear_many_payloads/3.

clear_many_payloads/2

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

See also: clear_many_payloads/3.

clear_many_payloads/3

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

See also: delete_many/3, put/4, khepri:clear_many_payloads/3.

Overview

Generated by EDoc