[CLIENT-4436] Add quality-of-life improvements for path expressions

aerospike_helpers/cdt_ctx.py

@@ -100,6 +100,18 @@
     # Cleanup
     client.remove(key)
     client.close()
+
+.. _path_expressions_contexts:
+
+Path Expressions Contexts
+-------------------------
+
+These :py:class:`_cdt_ctx` methods are meant to be used with path expressions:
+
+- :py:meth:`cdt_ctx_all_children`
+- :py:meth:`cdt_ctx_all_children_with_filter`
+- :py:meth:`cdt_ctx_map_keys_in`
+- :py:meth:`cdt_ctx_and_filter`
 """
 import aerospike
 
@@ -301,6 +313,8 @@ def cdt_ctx_map_key_create(key: any, order: int = 0) -> _cdt_ctx:
     """
     return _cdt_ctx(id=aerospike.CDT_CTX_MAP_KEY_CREATE, value=key, extra_args={CDT_CTX_ORDER_KEY: order})
 
+# Path expressions
+
 def cdt_ctx_all_children() -> _cdt_ctx:
     """
     At the current context, causes a query to return a list of all the children
@@ -326,3 +340,48 @@ def cdt_ctx_all_children_with_filter(expression: "TypeExpression") -> _cdt_ctx:
         :class:`~aerospike_helpers.cdt_ctx._cdt_ctx`
     """
     return _cdt_ctx(id=aerospike._AS_CDT_CTX_EXP, extra_args={aerospike._CDT_CTX_FILTER_EXPR_KEY: expression})
+
+def cdt_ctx_and_filter(expression: "TypeExpression") -> _cdt_ctx:
+    """
+    Add a boolean expression filter AND-combined with a previous :meth:`cdt_ctx_map_keys_in`.
+
+    This applies the expression at the same level as the previous path context.
+
+    Restrictions:
+
+    Only one :meth:`cdt_ctx_and_filter` is allowed per context level. Multiple :meth:`cdt_ctx_and_filter`
+    calls cannot be chained. To combine multiple conditions, use :class:`~aerospike_helpers.expressions.base.And` within
+    a single :meth:`cdt_ctx_and_filter`.
+
+    The preceding context entry must not be an expression type (i.e. :meth:`cdt_ctx_and_filter`
+    cannot follow :meth:`cdt_ctx_all_children_with_filter` or :meth:`cdt_ctx_all_children`).
+
+    :meth:`cdt_ctx_and_filter` cannot be the first entry in the context chain.
+
+    Args:
+        expression: Compiled expression. This expression must return a boolean.
+
+    Returns:
+        :class:`~aerospike_helpers.cdt_ctx._cdt_ctx`
+    """
+    return _cdt_ctx(id=aerospike._AS_CDT_CTX_AND | aerospike._AS_CDT_CTX_EXP, extra_args={aerospike._CDT_CTX_FILTER_EXPR_KEY: expression})
+
+def cdt_ctx_map_keys_in(keys: list):
+    """
+    Restrict map context to the given list of keys, provided they exist.
+
+    For example, if a map ``{"A": 1, "B": 2, "C": 3}`` exists, and you pass
+    keys ``["A", "C", "D"]`` in as the list of keys, the result will only
+    include ``{"A": 1, "C": 3}``, since element "D" does not exist in the map.
+
+    This can be followed by :meth:`cdt_ctx_and_filter` to filter out the remaining map entries.
+
+    This can only be used by path expressions.
+
+    Args:
+        keys (list): The keys to look for in the map.
+
+    Returns:
+        :class:`~aerospike_helpers.cdt_ctx._cdt_ctx`
+    """
+    return _cdt_ctx(id=aerospike._AS_CDT_CTX_MAP_KEYS_IN, value=keys)

aerospike_helpers/expressions/base.py

@@ -1161,7 +1161,8 @@ class SelectByPath(_BaseExpr):
     def __init__(self, ctx: list[_cdt_ctx], value_type: ResultType, flags: int, bin: _BaseExpr):
         """
         Args:
-            ctx: list of CDT contexts. This cannot be None or an empty list.
+            ctx: list of CDT contexts. This cannot be None or an empty list. See :ref:`path_expressions_contexts`
+                for possible contexts.
             value_type: Return type specifier.
             flags: See :ref:`exp_path_select_flags` for possible values.
             bin: Bin expression to which this expression applies.
@@ -1188,7 +1189,8 @@ class ModifyByPath(_BaseExpr):
     def __init__(self, ctx: list[_cdt_ctx], value_type: ResultType, mod_exp, flags: int, bin: _BaseExpr):
         """
         Args:
-            ctx: list of CDT contexts. This cannot be None or an empty list.
+            ctx: list of CDT contexts. This cannot be None or an empty list. See :ref:`path_expressions_contexts`
+                for possible contexts.
             value_type: Value type specifier.
             mod_exp: Compiled expression to apply.
             flags: See :ref:`exp_path_modify_flags` for possible values.

aerospike_helpers/expressions/list.py

@@ -941,6 +941,27 @@ def __init__(
             self._fixed[_Keys.CTX_KEY] = ctx
 
 
+class InList(_BaseExpr):
+    """
+    Return :py:obj:`True` if value is contained in list. Otherwise return :py:obj:`False`.
+    """
+
+    _op = aerospike._AS_EXP_CODE_IN_LIST
+
+    def __init__(
+        self,
+        value: "TypeValue",
+        bin: "TypeBinName",
+    ):
+        """Args:
+            value (TypeValue): Value or value expression to look for.
+            bin (TypeBinName): list bin name or expression evaluating to a list.
+
+        :return: Expression.
+        """
+        self._children = (value, bin if isinstance(bin, _BaseExpr) else ListBin(bin))
+
+
 class ListGetByValueRelRankRange(_BaseExpr):
     """Create an expression that selects list items nearest to value and greater by relative rank with a
     count limit and returns selected data specified by return_type.

aerospike_helpers/expressions/map.py

@@ -1488,3 +1488,45 @@ def __init__(
 
         if ctx is not None:
             self._fixed[_Keys.CTX_KEY] = ctx
+
+
+class MapGetKeys(_BaseExpr):
+    """
+    Return a list of keys from a map.
+    """
+
+    _op = aerospike._AS_EXP_CODE_MAP_KEYS
+
+    def __init__(
+        self,
+        map_value
+    ):
+        """Args:
+            map_value (TypeBinName): expression that returns a map, or bin name containing a map.
+
+        :return: Expression.
+        """
+        if not isinstance(map_value, _BaseExpr):
+            map_value = MapBin(map_value)
+        self._children = (map_value,)
+
+
+class MapGetValues(_BaseExpr):
+    """
+    Return a list of values from a map.
+    """
+
+    _op = aerospike._AS_EXP_CODE_MAP_VALUES
+
+    def __init__(
+        self,
+        map_value
+    ):
+        """Args:
+            map_value (TypeBinName): expression that returns a map, or bin name containing a map.
+
+        :return: Expression.
+        """
+        if not isinstance(map_value, _BaseExpr):
+            map_value = MapBin(map_value)
+        self._children = (map_value,)

aerospike_helpers/operations/operations.py

@@ -142,6 +142,7 @@ def select_by_path(bin_name: str, ctx: list[_cdt_ctx], flags: int):
     Args:
         bin_name: Name of bin where this select operation is performed against.
         ctx: List of contexts to select nodes. It is an error for ctx to be :py:obj:`None` or an empty list.
+            See :ref:`path_expressions_contexts` for possible contexts.
         flags: See :ref:`exp_path_select_flags` for the set of valid flags for this function.
 
     Returns:
@@ -161,6 +162,7 @@ def modify_by_path(bin_name: str, ctx: list[_cdt_ctx], expr, flags: int):
     Args:
         bin_name: Name of bin that this modify operation is performed against
         ctx: List of contexts to select nodes. It is an error for ctx to be :py:obj:`None` or an empty list.
+            See :ref:`path_expressions_contexts` for possible contexts.
         expr: compiled modifying expression.
         flags: See :ref:`exp_path_modify_flags` for the set of valid flags for this function.
 

src/main/aerospike.c

@@ -447,9 +447,11 @@ static struct module_constant_name_to_value module_constants[] = {
     {"CDT_CTX_MAP_INDEX", .value.integer = AS_CDT_CTX_MAP_INDEX},
     {"CDT_CTX_MAP_RANK", .value.integer = AS_CDT_CTX_MAP_RANK},
     {"CDT_CTX_MAP_KEY", .value.integer = AS_CDT_CTX_MAP_KEY},
+    EXPOSE_AS_MACRO_AS_PRIVATE_FIELD(AS_CDT_CTX_MAP_KEYS_IN),
     {"CDT_CTX_MAP_VALUE", .value.integer = AS_CDT_CTX_MAP_VALUE},
     {"CDT_CTX_MAP_KEY_CREATE", .value.integer = CDT_CTX_MAP_KEY_CREATE},
     EXPOSE_AS_MACRO_AS_PRIVATE_FIELD(AS_CDT_CTX_EXP),
+    EXPOSE_AS_MACRO_AS_PRIVATE_FIELD(AS_CDT_CTX_AND),
 
     /* HLL constants 3.11.0 */
     {"OP_HLL_ADD", .value.integer = OP_HLL_ADD},
@@ -585,7 +587,11 @@ static struct module_constant_name_to_value module_constants[] = {
     // so we define unique ones in the Python client code
     EXPOSE_MACRO(_AS_EXP_CODE_CALL_SELECT),
     EXPOSE_MACRO(_AS_EXP_CODE_CALL_APPLY),
+
     EXPOSE_MACRO(_AS_EXP_CODE_REMOVE_RESULT),
+    EXPOSE_MACRO(_AS_EXP_CODE_IN_LIST),
+    EXPOSE_MACRO(_AS_EXP_CODE_MAP_KEYS),
+    EXPOSE_MACRO(_AS_EXP_CODE_MAP_VALUES),
 
     EXPOSE_STRING_MACRO_FOR_AEROSPIKE_HELPERS(_CDT_FLAGS_KEY),
     EXPOSE_STRING_MACRO_FOR_AEROSPIKE_HELPERS(_CDT_APPLY_MOD_EXP_KEY),