[CLIENT-3752] Add support for path expressions and operations

.gitmodules

@@ -2,4 +2,4 @@
 	path = aerospike-client-c
 	# url = [email protected]:aerospike/aerospike-client-c.git
 	url = https://github.com/aerospike/aerospike-client-c.git
-	branch = stage
+	branch = client-3753-path-expressions-integration

aerospike-stubs/aerospike.pyi

@@ -309,6 +309,19 @@ TXN_STATE_VERIFIED: Literal[1]
 TXN_STATE_COMMITTED: Literal[2]
 TXN_STATE_ABORTED: Literal[3]
 
+CDT_SELECT_MATCHING_TREE: Literal[0]
+CDT_SELECT_VALUES: Literal[1]
+CDT_SELECT_MAP_KEY_VALUES: Literal[1]
+CDT_SELECT_MAP_KEYS: Literal[2]
+CDT_SELECT_NO_FAIL: Literal[16]
+
+CDT_MODIFY_DEFAULT: Literal[0]
+CDT_MODIFY_NO_FAIL: Literal[0x10]
+
+EXP_LOOPVAR_KEY: Literal[0]
+EXP_LOOPVAR_VALUE: Literal[1]
+EXP_LOOPVAR_INDEX: Literal[2]
+
 @final
 class CDTInfinite:
     def __init__(self, *args, **kwargs) -> None: ...

aerospike_helpers/cdt_ctx.py

@@ -300,3 +300,29 @@ def cdt_ctx_map_key_create(key: any, order: int = 0) -> _cdt_ctx:
         :class:`~aerospike_helpers.cdt_ctx._cdt_ctx`
     """
     return _cdt_ctx(id=aerospike.CDT_CTX_MAP_KEY_CREATE, value=key, extra_args={CDT_CTX_ORDER_KEY: order})
+
+def cdt_ctx_all_children() -> _cdt_ctx:
+    """
+    At the current context, causes a query to return a list of all the children
+    of the current item. For a map, this will recurse into the map elements.
+    For a list, this will include all the children in the list.
+
+    Returns:
+        :class:`~aerospike_helpers.cdt_ctx._cdt_ctx`
+    """
+    return _cdt_ctx(id=aerospike._CDT_CTX_EXP)
+
+def cdt_ctx_all_children_with_filter(expression: "TypeExpression") -> _cdt_ctx:
+    """
+    All children of the current level will be selected, and then the filter expression
+    is applied to each item in turn.  Items that cause the expression to evaluate to true will be added to the
+    list of items returned in a query for this level.  Items that cause the expression to evaluate to false
+    will be filtered out
+
+    Args:
+        expression: Compiled expression. This expression must return a boolean.
+
+    Returns:
+        :class:`~aerospike_helpers.cdt_ctx._cdt_ctx`
+    """
+    return _cdt_ctx(id=aerospike._CDT_CTX_EXP, extra_args={aerospike._CDT_CTX_ALL_CHILDREN_WITH_FILTER_EXPR_KEY: expression})

aerospike_helpers/expressions/base.py

@@ -32,6 +32,8 @@
 from aerospike_helpers.expressions.resources import _ExprOp
 from aerospike_helpers.expressions.resources import ResultType
 from aerospike_helpers.expressions.resources import _Keys
+from aerospike_helpers.cdt_ctx import _cdt_ctx
+from abc import ABC
 
 TypeComparisonArg = Union[_BaseExpr, Any]
 TypeGeo = Union[_BaseExpr, aerospike.GeoJSON]
@@ -1069,3 +1071,91 @@ def __init__(self, var_name: str):
                         exp.LT(exp.Var("x"), 10))).compile()
         """
         self._fixed = {_Keys.VALUE_KEY: var_name}
+
+
+class LoopVar(_BaseExpr, ABC):
+    """
+    Retrieve expression value from a path expression loop variable.
+    """
+    def __init__(self, var_id: int):
+        """
+        Args:
+            var_id: See :ref:`exp_loopvar_metadata` for possible values.
+
+        :return: (value stored in variable)
+        """
+        self._fixed = {_Keys.VALUE_KEY: var_id}
+
+
+class LoopVarMap(LoopVar):
+    _op = aerospike._AS_EXP_LOOPVAR_MAP
+
+
+class LoopVarList(LoopVar):
+    _op = aerospike._AS_EXP_LOOPVAR_LIST
+
+
+class LoopVarStr(LoopVar):
+    _op = aerospike._AS_EXP_LOOPVAR_STR
+
+
+class LoopVarFloat(LoopVar):
+    _op = aerospike._AS_EXP_LOOPVAR_FLOAT
+
+
+class LoopVarInt(LoopVar):
+    _op = aerospike._AS_EXP_LOOPVAR_INT
+
+
+class SelectByPath(_BaseExpr):
+    """
+    Constructs a select by path operation.  This is used to retrieve a number of
+    records or fields of records, including those of structured types.
+    """
+    _op = aerospike._AS_EXP_CODE_CALL_SELECT
+
+    def __init__(self, ctx: list[_cdt_ctx], return_type: ResultType, flags: int, bin: _BaseExpr):
+        """
+        Args:
+            ctx: list of CDT contexts. This cannot be None or an empty list.
+            return_type: Return type specifier.
+            flags: See :ref:`cdt_select_flags` for possible values.
+            bin: Bin expression to which this expression applies.
+
+        :return: (expression)
+        """
+        self._fixed = {
+            _Keys.RETURN_TYPE_KEY: return_type,
+            _Keys.CTX_KEY: ctx,
+            aerospike._CDT_FLAGS_KEY: flags,
+        }
+        self._children = (bin,)
+
+
+class ModifyByPath(_BaseExpr):
+    """
+    Constructs a CDT apply operation.
+
+    The results of the evaluation of the modifying expression will replace the
+    selected map, and the changes are written back to storage.
+    """
+    _op = aerospike._AS_EXP_CODE_CALL_APPLY
+
+    def __init__(self, ctx: list[_cdt_ctx], return_type: ResultType, mod_exp, flags: int, bin: _BaseExpr):
+        """
+        Args:
+            ctx: list of CDT contexts. This cannot be None or an empty list.
+            return_type: Return type specifier.
+            mod_exp: Compiled expression to apply.
+            flags: See :ref:`cdt_modify_flags` for possible values.
+            bin: Bin expression to which this expression applies.
+
+        :return: (expression)
+        """
+        self._fixed = {
+            _Keys.RETURN_TYPE_KEY: return_type,
+            _Keys.CTX_KEY: ctx,
+            aerospike._CDT_FLAGS_KEY: flags,
+            aerospike._CDT_APPLY_MOD_EXP_KEY: mod_exp
+        }
+        self._children = (bin,)

aerospike_helpers/expressions/resources.py

@@ -87,6 +87,7 @@ class _ExprOp:  # TODO replace this with an enum
     DEF = 126
 
     _AS_EXP_CODE_AS_VAL = 128
+
     # virtual ops
     _AS_EXP_CODE_CALL_VOP_START = 139
     _AS_EXP_CODE_CDT_LIST_CRMOD = 140
@@ -112,6 +113,8 @@ class ReturnType:
     MAP_RETURN_INVERTED = 0x10000
 
 
+# These enum constants must match the values for C client's as_exp_type.
+# These are passed as arguments to ModifyByPath and SelectByPath expressions
 class ResultType:
     """
     Flags used to indicate expression value_type.

aerospike_helpers/operations/operations.py

@@ -24,6 +24,8 @@
 import aerospike
 from typing import Optional
 
+from aerospike_helpers.cdt_ctx import _cdt_ctx
+
 
 def read(bin_name):
     """Create a read operation dictionary.
@@ -131,3 +133,44 @@ def touch(ttl: Optional[int] = None):
         warnings.warn("TTL should be specified in the meta dictionary for operate", DeprecationWarning)
         op_dict["val"] = ttl
     return op_dict
+
+
+def select_by_path(bin_name: str, ctx: list[_cdt_ctx], flags: int):
+    """
+    Create CDT select operation.
+
+    Args:
+        bin_name: Bin name
+        ctx: List of contexts to select nodes. It is an error for ctx to be :py:obj:`None` or an empty list.
+        flags: See :ref:`cdt_select_flags` for the set of valid flags for this function.
+
+    Returns:
+        A dictionary to be passed to operate or operate_ordered.
+    """
+    op_dict = {"op": aerospike._AS_OPERATOR_CDT_READ, "bin": bin_name, "ctx": ctx, aerospike._CDT_FLAGS_KEY: flags}
+    return op_dict
+
+
+def modify_by_path(bin_name: str, ctx: list[_cdt_ctx], expr, flags: int):
+    """
+    Create CDT modification operation.
+
+    The results of the evaluation of the modifying expression will replace the
+    selected map, and the changes are written back to storage.
+
+    Args:
+        bin_name: Bin name
+        ctx: List of contexts to select nodes. It is an error for ctx to be :py:obj:`None` or an empty list.
+        expr: compiled modifying expression.
+        flags: See :ref:`cdt_modify_flags` for the set of valid flags for this function.
+
+    Returns:
+        A dictionary to be passed to operate or operate_ordered.
+    """
+    op_dict = {
+        "op": aerospike._AS_OPERATOR_CDT_MODIFY,
+        "bin": bin_name,
+        "ctx": ctx, aerospike._CDT_APPLY_MOD_EXP_KEY: expr,
+        aerospike._CDT_FLAGS_KEY: flags
+    }
+    return op_dict

doc/aerospike.rst

@@ -1792,3 +1792,61 @@ Transaction State
 .. data:: TXN_STATE_COMMITTED
 
 .. data:: TXN_STATE_ABORTED
+
+.. _cdt_select_flags:
+
+CDT Select Flags
+----------------
+
+.. data:: CDT_SELECT_MATCHING_TREE
+
+    Return a tree from the root (bin) level to the bottom of the tree, with only non-filtered out nodes.
+
+.. data:: CDT_SELECT_VALUES
+
+    Return the list of the values of the nodes finally selected by the context.
+
+.. data:: CDT_SELECT_MAP_KEY_VALUES
+
+    Return a list of key-value pairs.
+
+.. data:: CDT_SELECT_MAP_KEYS
+
+    For final selected nodes which are elements of maps, return the appropriate map key.
+
+.. data:: CDT_SELECT_NO_FAIL
+
+    If the expression in the context hits an invalid type (e.g selects as an integer when the value is a string),
+    do not fail the operation; just ignore those elements.
+
+.. _cdt_modify_flags:
+
+CDT Modify Flags
+----------------
+
+.. data:: CDT_MODIFY_DEFAULT
+
+    If the expression in the context hits an invalid type, the operation
+    will fail.  This is the default behavior.
+
+.. data:: CDT_MODIFY_NO_FAIL
+
+    If the expression in the context hits an invalid type (e.g., selects as an integer when the value is a string), do
+    not fail the operation; just ignore those elements.
+
+.. _exp_loopvar_metadata:
+
+Expression Loop Variable Metadata
+---------------------------------
+
+.. data:: EXP_LOOPVAR_KEY
+
+    The key associated with this value if part of a key-value pair of a map.
+
+.. data:: EXP_LOOPVAR_VALUE
+
+    List item, or value from a map key-value pair.
+
+.. data:: EXP_LOOPVAR_INDEX
+
+    The index if this element was part of a list.

doc/aerospike_helpers.expressions.rst

@@ -167,6 +167,7 @@ aerospike\_helpers\.expressions\.base module
 .. automodule:: aerospike_helpers.expressions.base
     :members:
     :special-members:
+    :show-inheritance:
 
 aerospike\_helpers\.expressions\.list module
 --------------------------------------------

doc/spelling_wordlist.txt

@@ -91,3 +91,4 @@ namespaces
 yaml
 suberror
 hardcoded
+recurse

src/include/policy.h

@@ -170,8 +170,28 @@ enum aerospike_hll_operations {
     OP_HLL_MAY_CONTAIN
 };
 
+enum {
+    _AS_EXP_CODE_CALL_SELECT = 127,
+    _AS_EXP_CODE_CALL_APPLY = 129,
+};
+
 enum aerospike_expression_operations { OP_EXPR_READ = 2200, OP_EXPR_WRITE };
 
+// Module constants to be used by aerospike_helpers
+
+enum {
+    _AS_EXP_LOOPVAR_FLOAT = 3000,
+    _AS_EXP_LOOPVAR_INT,
+    _AS_EXP_LOOPVAR_LIST,
+    _AS_EXP_LOOPVAR_MAP,
+    _AS_EXP_LOOPVAR_STR
+};
+
+// Can be either for select or apply
+#define _CDT_FLAGS_KEY "cdt_flags"
+#define _CDT_APPLY_MOD_EXP_KEY "mod_exp"
+#define _CDT_CTX_ALL_CHILDREN_WITH_FILTER_EXPR_KEY "filter_expr"
+
 enum aerospike_regex_constants {
     REGEX_NONE = 0,
     REGEX_EXTENDED,