[CLIENT-3961] Add missing LoopVarHLL and unhide documentation for path expressions (#899)

Fix modify_by_path operation and ModifyByPath expression docstring

Author: juliannguyen4

aerospike_helpers/expressions/base.py

@@ -1120,11 +1120,6 @@ class LoopVarBool(LoopVar):
     _op = aerospike._AS_EXP_LOOPVAR_BOOL
 
 
-# TODO: remove?
-# class LoopVarInfinity(LoopVar):
-#     _op = aerospike._AS_EXP_LOOPVAR_INF
-
-
 class LoopVarNil(LoopVar):
     _op = aerospike._AS_EXP_LOOPVAR_NIL
 
@@ -1133,9 +1128,13 @@ class LoopVarGeoJson(LoopVar):
     _op = aerospike._AS_EXP_LOOPVAR_GEOJSON
 
 
+class LoopVarHLL(LoopVar):
+    _op = aerospike._AS_EXP_LOOPVAR_HLL
+
+
 class ResultRemove(_BaseExpr):
     """
-    Indicates entry deletion for modify_by_path.
+    Indicates entry deletion for :py:class:`ModifyByPath`.
     """
     _op = aerospike._AS_EXP_CODE_RESULT_REMOVE
 
@@ -1176,7 +1175,7 @@ class ModifyByPath(_BaseExpr):
     Constructs an apply by path operation.
 
     The results of the evaluation of the modifying expression will replace the
-    selected map, and the changes are written back to storage.
+    selected element, and the changes are written back to storage.
     """
     _op = aerospike._AS_EXP_CODE_CALL_APPLY
 

aerospike_helpers/operations/operations.py

@@ -156,7 +156,7 @@ def modify_by_path(bin_name: str, ctx: list[_cdt_ctx], expr, flags: int):
     Create path expression modification operation.
 
     The results of the evaluation of the modifying expression will replace the
-    selected map, and the changes are written back to storage.
+    selected element, and the changes are written back to storage.
 
     Args:
         bin_name: Name of bin that this modify operation is performed against

doc/aerospike.rst

@@ -1810,76 +1810,77 @@ Transaction State
 
 .. data:: TXN_STATE_ABORTED
 
-..
-    Path Expression Flags
-    ---------------------
+.. _exp_path_select_flags:
 
-    .. data:: EXP_PATH_SELECT_MATCHING_TREE
+Path Expression Select Flags
+----------------------------
 
-        Return a tree from the root (bin) level to the bottom of the tree, with only non-filtered out nodes.
+.. data:: EXP_PATH_SELECT_MATCHING_TREE
 
-    .. data:: EXP_PATH_SELECT_VALUE
+    Return a tree from the root (bin) level to the bottom of the tree, with only non-filtered out nodes.
 
-        Return the list of the values of the nodes finally selected by the context.
+.. data:: EXP_PATH_SELECT_VALUE
 
-        For maps, this returns the value of each (key, value) pair.
+    Return the list of the values of the nodes finally selected by the context.
 
-    .. data:: EXP_PATH_SELECT_LIST_VALUE
+    For maps, this returns the value of each (key, value) pair.
 
-        Return the list of the values of the nodes finally selected by the context.
-        This is a synonym for :data:`aerospike.EXP_PATH_SELECT_VALUE` to make it clear in your
-        source code that you're expecting a list.
+.. data:: EXP_PATH_SELECT_LIST_VALUE
 
-    .. data:: EXP_PATH_SELECT_MAP_VALUE
+    Return the list of the values of the nodes finally selected by the context.
+    This is a synonym for :data:`aerospike.EXP_PATH_SELECT_VALUE` to make it clear in your
+    source code that you're expecting a list.
 
-        Return the list of map values of the nodes finally selected by the context.
-        This is a synonym for :data:`aerospike.EXP_PATH_SELECT_VALUE` to make it clear in your
-        source code that you're expecting a map.  See also :data:`aerospike.EXP_PATH_SELECT_MAP_KEY_VALUE`.
+.. data:: EXP_PATH_SELECT_MAP_VALUE
 
-    .. data:: EXP_PATH_SELECT_MAP_KEYS
+    Return the list of map values of the nodes finally selected by the context.
+    This is a synonym for :data:`aerospike.EXP_PATH_SELECT_VALUE` to make it clear in your
+    source code that you're expecting a map.  See also :data:`aerospike.EXP_PATH_SELECT_MAP_KEY_VALUE`.
 
-        Return the list of map keys of the nodes finally selected by the context.
+.. data:: EXP_PATH_SELECT_MAP_KEYS
 
-    .. data:: EXP_PATH_SELECT_MAP_KEY_VALUE
+    Return the list of map keys of the nodes finally selected by the context.
 
-        Returns the list of map (key, value) pairs of the nodes finally selected
-        by the context. This is a synonym for setting both
-        :data:`aerospike.EXP_PATH_SELECT_MAP_KEY` and :data:`aerospike.EXP_PATH_SELECT_MAP_VALUE`` bits together.
-        The list is formatted as ``[key0, value0, key1, value1...]``.
+.. data:: EXP_PATH_SELECT_MAP_KEY_VALUE
 
-    .. data:: EXP_PATH_SELECT_NO_FAIL
+    Returns the list of map (key, value) pairs of the nodes finally selected
+    by the context. This is a synonym for setting both
+    :data:`aerospike.EXP_PATH_SELECT_MAP_KEY` and :data:`aerospike.EXP_PATH_SELECT_MAP_VALUE` bits together.
+    The list is formatted as ``[key0, value0, key1, value1...]``.
 
-        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. Interpret UNKNOWN as false instead.
+.. data:: EXP_PATH_SELECT_NO_FAIL
 
-    .. _exp_path_modify_flags:
+    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. Interpret UNKNOWN as false instead.
 
-    CDT Modify Flags
-    ----------------
+.. _exp_path_modify_flags:
 
-    .. data:: EXP_PATH_MODIFY_DEFAULT
+Path Expression Modify Flags
+----------------------------
 
-        If the expression in the context hits an invalid type, the operation
-        will fail.  This is the default behavior.
+.. data:: EXP_PATH_MODIFY_DEFAULT
 
-    .. data:: EXP_PATH_MODIFY_NO_FAIL
+    If the expression in the context hits an invalid type, the operation
+    will fail.  This is the default behavior.
 
-        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. Interpret UNKNOWN as false instead.
+.. data:: EXP_PATH_MODIFY_NO_FAIL
 
-    .. _exp_loopvar_metadata:
+    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. Interpret UNKNOWN as false instead.
 
-    Expression Loop Variable Metadata
-    ---------------------------------
+.. _exp_loopvar_metadata:
 
-    .. data:: EXP_LOOPVAR_KEY
+Path Expression Loop Variable Metadata
+--------------------------------------
 
-        The key associated with this value if part of a key-value pair of a map.
+.. data:: EXP_LOOPVAR_KEY
 
-    .. data:: EXP_LOOPVAR_VALUE
+    The key associated with this value if part of a key-value pair of a map.
 
-        List item, or value from a map key-value pair.
+.. data:: EXP_LOOPVAR_VALUE
 
-    .. data:: EXP_LOOPVAR_INDEX
+    List item, or value from a map key-value pair.
 
-        The index if this element was part of a list.
+.. data:: EXP_LOOPVAR_INDEX
+
+    The index if this element was part of a list.

doc/aerospike_helpers.cdt_ctx.rst

@@ -7,6 +7,5 @@ aerospike\_helpers\.cdt_ctx module
 
 .. automodule:: aerospike_helpers.cdt_ctx
     :members:
-    :exclude-members: cdt_ctx_all_children, cdt_ctx_all_children_with_filter
     :undoc-members:
     :show-inheritance:

doc/aerospike_helpers.expressions.rst

@@ -165,7 +165,6 @@ aerospike\_helpers\.expressions\.base module
 ---------------------------------------------
 
 .. automodule:: aerospike_helpers.expressions.base
-    :exclude-members: LoopVar, LoopVarMap, LoopVarList, LoopVarStr, LoopVarFloat, LoopVarInt, LoopVarBlob, LoopVarBool, LoopVarNil, LoopVarGeoJson, SelectByPath, ModifyByPath, ResultRemove
     :members:
     :special-members:
     :show-inheritance:

doc/aerospike_helpers.operations.rst

@@ -8,7 +8,6 @@ aerospike\_helpers\.operations\.operations module
 
 .. automodule:: aerospike_helpers.operations.operations
     :members:
-    :exclude-members: select_by_path, modify_by_path
     :undoc-members:
     :show-inheritance:
 

src/include/policy.h

@@ -182,9 +182,9 @@ enum {
     _AS_EXP_LOOPVAR_STR,
     _AS_EXP_LOOPVAR_BLOB,
     _AS_EXP_LOOPVAR_BOOL,
-    // _AS_EXP_LOOPVAR_INF,
     _AS_EXP_LOOPVAR_NIL,
     _AS_EXP_LOOPVAR_GEOJSON,
+    _AS_EXP_LOOPVAR_HLL,
     _AS_EXP_CODE_CALL_SELECT,
     _AS_EXP_CODE_CALL_APPLY,
 };

src/main/aerospike.c

@@ -586,9 +586,9 @@ static struct module_constant_name_to_value module_constants[] = {
     EXPOSE_MACRO(_AS_EXP_LOOPVAR_STR),
     EXPOSE_MACRO(_AS_EXP_LOOPVAR_BLOB),
     EXPOSE_MACRO(_AS_EXP_LOOPVAR_BOOL),
-    // EXPOSE_MACRO(_AS_EXP_LOOPVAR_INF),
     EXPOSE_MACRO(_AS_EXP_LOOPVAR_NIL),
     EXPOSE_MACRO(_AS_EXP_LOOPVAR_GEOJSON),
+    EXPOSE_MACRO(_AS_EXP_LOOPVAR_HLL),
 
     // C client uses the same expression code for these two expressions
     // so we define unique ones in the Python client code

src/main/convert_expressions.c

@@ -222,7 +222,7 @@ static as_status get_expr_size(int *size_to_alloc, int *intermediate_exprs_size,
         [_AS_EXP_LOOPVAR_BLOB] = EXP_SZ(as_exp_loopvar_blob(0)),
         [_AS_EXP_LOOPVAR_GEOJSON] = EXP_SZ(as_exp_loopvar_geojson(0)),
         [_AS_EXP_LOOPVAR_NIL] = EXP_SZ(as_exp_loopvar_nil(0)),
-        // [_AS_EXP_LOOPVAR_INF] = EXP_SZ(as_exp_loopvar_infinity(0)),
+        [_AS_EXP_LOOPVAR_HLL] = EXP_SZ(as_exp_loopvar_hll(0)),
         [VAL] = EXP_SZ(as_exp_val(
             NULL)), // NOTE if I don't count vals I don't need to subtract from other ops // MUST count these for expressions with var args.
         [EQ] = EXP_SZ(
@@ -661,6 +661,7 @@ add_expr_macros(AerospikeClient *self, as_static_pool *static_pool,
         case _AS_EXP_LOOPVAR_BOOL:
         case _AS_EXP_LOOPVAR_BLOB:
         case _AS_EXP_LOOPVAR_NIL:
+        case _AS_EXP_LOOPVAR_HLL:
         case _AS_EXP_LOOPVAR_GEOJSON:
             if (get_int64_t(err, AS_PY_VAL_KEY, temp_expr->pydict, &lval1) !=
                 AEROSPIKE_OK) {
@@ -695,6 +696,9 @@ add_expr_macros(AerospikeClient *self, as_static_pool *static_pool,
             case _AS_EXP_LOOPVAR_GEOJSON:
                 APPEND_ARRAY(0, as_exp_loopvar_geojson(lval1));
                 break;
+            case _AS_EXP_LOOPVAR_HLL:
+                APPEND_ARRAY(0, as_exp_loopvar_hll(lval1));
+                break;
             }
 
             break;

test/new_tests/test_path_expressions.py

@@ -2,11 +2,14 @@
 
 import aerospike
 from aerospike_helpers.operations import operations
+from aerospike_helpers.operations import hll_operations as hll_ops
+from aerospike_helpers.operations import map_operations
 from aerospike_helpers.expressions.resources import ResultType
-from aerospike_helpers.expressions.base import GE, Eq, LoopVarStr, LoopVarFloat, LoopVarInt, LoopVarMap, LoopVarList, ModifyByPath, SelectByPath, MapBin, LoopVarBool, LoopVarBlob, ResultRemove, LoopVarGeoJson, LoopVarNil, CmpGeo
-from aerospike_helpers.expressions.map import MapGetByKey
+from aerospike_helpers.expressions.base import GE, Eq, LoopVarStr, LoopVarFloat, LoopVarInt, LoopVarMap, LoopVarList, ModifyByPath, SelectByPath, MapBin, LoopVarBool, LoopVarBlob, ResultRemove, LoopVarGeoJson, LoopVarNil, CmpGeo, LoopVarHLL, HLLBin
+from aerospike_helpers.expressions.map import MapGetByKey, MapPut
 from aerospike_helpers.expressions.list import ListSize
 from aerospike_helpers.expressions.arithmetic import Sub
+from aerospike_helpers.expressions import hll
 from aerospike_helpers.operations import expression_operations as expr_ops
 from aerospike_helpers import cdt_ctx
 from aerospike import exception as e
@@ -30,7 +33,7 @@ class TestPathExprOperations:
     MAP_OF_NESTED_MAPS_BIN_NAME = "map_of_maps_bin"
     NESTED_LIST_BIN_NAME = "list_of_lists"
     MAP_WITH_GEOJSON_BIN_NAME = "map_w_geo_bin"
-    
+
     GEOJSON_VALUE = aerospike.geojson('{"type": "Point", "coordinates": [-80.604333, 28.608389]}')
     RECORD_BINS = {
         MAP_BIN_NAME: {
@@ -165,7 +168,7 @@ def insert_record(self):
             )
         ]
     )
-    def test_exp_path_basic_functionality(self, op, expected_bins):
+    def test_select_by_path_operation(self, op, expected_bins):
         ops = [
             op
         ]
@@ -178,7 +181,7 @@ def test_exp_path_basic_functionality(self, op, expected_bins):
         20.0
     ).compile()
 
-    def test_exp_path_with_filter(self):
+    def test_select_by_path_operation_with_filter(self):
         ops = [
             operations.select_by_path(
                 bin_name=self.MAP_OF_NESTED_MAPS_BIN_NAME,
@@ -296,6 +299,44 @@ def test_exp_loopvar_list(self):
                 [4, 5]
             ]
 
+    MAP_WITH_HLL_BIN_NAME = "map_w_hll_bin"
+
+    @pytest.fixture
+    def setup_hll_bin(self):
+        ops = [
+            # Insert root level HLL bin
+            # Using a second operation to move the hll value into a map doesn't work...
+            hll_ops.hll_add(bin_name=self.MAP_WITH_HLL_BIN_NAME, values=[i for i in range(5000)], index_bit_count=4, mh_bit_count=4),
+        ]
+        self.as_connection.operate(self.key, ops)
+
+        _, _, bins = self.as_connection.get(self.key)
+        self.expected_hll_value = bins[self.MAP_WITH_HLL_BIN_NAME]
+
+        map_with_hll_value = {
+            "a": bins[self.MAP_WITH_HLL_BIN_NAME]
+        }
+        self.as_connection.put(self.key, bins={self.MAP_WITH_HLL_BIN_NAME: map_with_hll_value})
+
+        yield
+
+        self.as_connection.remove_bin(self.key, list=[self.MAP_WITH_HLL_BIN_NAME])
+
+    def test_exp_loopvar_hll(self, setup_hll_bin):
+        # HLL bin value should always be returned
+        filter_expr = GE(hll.HLLGetCount(bin=LoopVarHLL(var_id=aerospike.EXP_LOOPVAR_VALUE)), 0).compile()
+        ops = [
+            operations.select_by_path(
+                bin_name=self.MAP_WITH_HLL_BIN_NAME,
+                ctx=[
+                    cdt_ctx.cdt_ctx_all_children_with_filter(filter_expr)
+                ],
+                flags=aerospike.EXP_PATH_SELECT_VALUE
+            )
+        ]
+        with self.expected_context_for_pos_tests:
+            _, _, bins = self.as_connection.operate(self.key, ops)
+            assert bins[self.MAP_WITH_HLL_BIN_NAME] == [self.expected_hll_value]
 
     SUBTRACT_FIVE_FROM_ITERATED_FLOAT_EXPR = Sub(LoopVarFloat(aerospike.EXP_LOOPVAR_VALUE), 5.0).compile()
     # Expected results
@@ -306,7 +347,7 @@ def test_exp_loopvar_list(self):
         aerospike.EXP_PATH_MODIFY_NO_FAIL,
         aerospike.EXP_PATH_MODIFY_DEFAULT,
     ])
-    def test_cdt_modify(self, flags):
+    def test_modify_by_path_operation(self, flags):
         ops = [
             operations.modify_by_path(
                 bin_name=self.MAP_OF_NESTED_MAPS_BIN_NAME,
@@ -332,7 +373,7 @@ def test_cdt_modify(self, flags):
             assert bins[self.MAP_OF_NESTED_MAPS_BIN_NAME] == self.SECOND_LEVEL_INTEGERS_MINUS_FIVE
 
 
-    # Test path expression flags
+    # Test path expression select flags
 
     def test_exp_path_flag_matching_tree(self):
         ops = [
@@ -457,7 +498,7 @@ def test_neg_invalid_ctx(self, ctx_list, expected_context, op_method, op_kwargs)
         with expected_context:
             self.as_connection.operate(self.key, ops)
 
-    def test_exp_select_by_path(self):
+    def test_select_by_path_expression(self):
         ctx=[
             cdt_ctx.cdt_ctx_all_children(),
             cdt_ctx.cdt_ctx_all_children()