Path expressions usage examples

PREVIEW

This feature is ready for testing but we recommend using it only in non-production environments. It is subject to change and may not be feature-complete. Aerospike provides no SLAs or technical support commitments for this preview.

This page contains advanced examples of using path expressions to select elements from a document modeled in Aerospike as nested map and list structures.

The quickstart guide covers a common use case: filtering and selecting products and their in-stock variants. This section highlights advanced capabilities unlocked by path expressions.

Note

All the examples on this page use the same data structure and setup as the examples in the quickstart.

Accessing iteration data from a map key, list index or element value with a LoopVar

When using a path expression to iterate over map or lsit elements, you can assign data from the element in this iteration to loop variables.

Example: Select only products whose key starts with SKU 1000.

Java

Exp filterOnKey = Exp.regexCompare("10000.*", 0, Exp.stringLoopVar(LoopVarPart.MAP_KEY));

// Operation
Record record = client.operate(null, key,
    CdtOperation.selectByPath("inventory", Exp.SELECT_MATCHING_TREE,
        CTX.allChildren(),
        CTX.allChildrenWithFilter(filterOnKey)));

System.out.println(record.getList("inventory"));

Python

from aerospike_helpers.expressions import expressions as exp

filter_on_key = CmpRegex(LoopVarStr(aerospike.EXP_PATH_SELECT_MAP_KEYS), exp.Val("1000")).compile

ops = [operations.select_by_path("inventory",
       cdt_ctx.all_children_with_filter(filter_on_key),
       aerospike.EXP_PATH_SELECT_MATCHING_TREE)]
(key, meta, bins) = client.operate(key, ops)
print(bins["inventory"])

Go

filterOnKey := aero.ExpRegexCompare("10000.*", aero.ExpRegexFlagNONE, aero.ExpStringLoopVar(aero.MAP_KEY))

regexMatchingTree, err := client.Operate(nil, key,
  aero.SelectByPath(binName, aero.EXP_PATH_SELECT_MATCHING_TREE,
    aero.CtxAllChildren(),
    aero.CtxAllChildrenWithFilter(filterOnKey),
  ),
)

fmt.Println(record.Bins["inventory"])

C

// Filter

as_exp_build(filter_on_key, as_exp_cmp_regex(
    REG_ICASE | REG_NEWLINE, as_exp_str("1000.*"),
    as_exp_loopvar_map(AS_EXP_LOOPVAR_KEY)
));
if (!filter_on_key) {
    goto fail_filter_on_key;
}

// Operation

as_cdt_ctx ctx;
as_cdt_ctx_inita(&ctx, 1);
as_cdt_ctx_add_all_children_with_filter(&ctx, filter_on_key);

as_operations ops;
as_operations_inita(&ops, 1);
status = as_operations_select_by_path(&err, &ops, "testbin", &ctx,
    AS_EXP_PATH_SELECT_MATCHING_TREE | AS_EXP_PATH_SELECT_NO_FAIL);
if (status != AEROSPIKE_OK) {
    goto fail_select_by_path;
}

as_record* rec = NULL;
status = aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
if (status != AEROSPIKE_OK) {
    goto fail_key_operate;
}

// Print in JSON format

as_map* map = as_record_get_map(rec, "testbin");
if (map) {
    char* map_str = as_val_tostring((as_val*)map);
    log("%s\n", map_str);
    free(map_str);
} else {
    log("No data returned\n");
}

C#

Exp filterOnKey =
    Exp.RegexCompare("10000.*", 0, Exp.StringLoopVar(LoopVarPart.MAP_KEY)
  );

  // Operation
  Record record = client.Operate(null, key,
    CDTOperation.SelectByPath(inventoryBinName, SelectFlag.MATCHING_TREE,
      CTX.AllChildren(),
      CTX.AllChildrenWithFilter(filterOnKey)
    )
  );
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize((Dictionary<object, object>)record.GetMap("inventory"), new System.Text.Json.JsonSerializerOptions { WriteIndented = true }));

Expected output:

 {
  "inventory": {
    "10000001": { ... },
    "10000002": { ... },
    "10000003": { ... }
  }
}

✅ Only products whose keys start with 1000 are included.

Use alternative return modes with SelectFlags

Sometimes you don’t want the full tree, but just the map keys or values.

Example: Return only the SKUs of in-stock variants for featured products that follow a map/dictionary structure.

Java

Record readResult = client.operate(null, key,
    CdtOperation.selectByPath(binName, Exp.SELECT_MATCHING_TREE,
        CTX.allChildren(),
        CTX.allChildrenWithFilter(filterOnFeatured),
        CTX.mapKey(Value.get("variants")),
        CTX.allChildrenWithFilter(filterOnVariantInventory)
    )
);

Python

ops = [operations.select_by_path("inventory",
       cdt_ctx.all_children_with_filter(filter_on_featured),
       aerospike.EXP_PATH_SELECT_MAP_KEYS),
       cdt_ctx.all_children(),
       cdt_ctx.all_children_with_filter(filter_on_variant_inventory)]
(key, meta, bins) = client.operate(key, ops)
print(bins["inventory"])

Go

// Operation with path expression
  readResult, err := client.Operate(nil, key,
    aero.SelectByPath(binName, aero.EXP_PATH_SELECT_MAP_KEY
      aero.CtxAllChildren(),
      aero.CtxAllChildrenWithFilter(filterOnFeatured),
      aero.CtxMapKey(aero.NewValue("variants")),
      aero.CtxAllChildrenWithFilter(filterOnVariantInventory),
    ),
  )
fmt.Println(record.Bins["inventory"])

C

// Details elided for brevity
as_exp_build(filter_on_featured, ...);
as_exp_build(filter_on_variant_inventory, ...);

// Operation

as_cdt_ctx ctx;
as_cdt_ctx_inita(&ctx, 3);
as_cdt_ctx_add_all_children_with_filter(&ctx, filter_on_featured);
as_cdt_ctx_add_all_children(&ctx),
as_cdt_ctx_add_all_children_with_filter(&ctx, filter_on_variant_inventory);

as_operations ops;
as_operations_inita(&ops, 1);
status = as_operations_select_by_path(&err, &ops, "testbin", &ctx,
    AS_EXP_PATH_SELECT_MAP_KEY | AS_EXP_PATH_SELECT_NO_FAIL);
if (status != AEROSPIKE_OK) {
    goto fail_select_by_path;
}

as_record* rec = NULL;
status = aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
if (status != AEROSPIKE_OK) {
    goto fail_key_operate;
}

// Print in JSON format

as_map* map = as_record_get_map(rec, "testbin");
if (map) {
    char* map_str = as_val_tostring((as_val*)map);
    log("%s\n", map_str);
    free(map_str);
} else {
    log("No data returned\n");
}

C#

Record record = client.Operate(null, key,
  CDTOperation.SelectByPath(inventoryBinName, SelectFlag.MATCHING_TREE,
    CTX.AllChildren(),
    CTX.AllChildrenWithFilter(filterOnKey)
  )
);
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize((Dictionary<object, object>)record.GetMap("inventory"), new System.Text.Json.JsonSerializerOptions { WriteIndented = true }));

Expected output:

["2001","2003"]

✅ Only the keys from SKU 10000001, Classic T-Shirt are returned.

⚠️ Item 50000009, Smart TV, has list-backed variants, so there are no map keys to return.

Modify nested elements with modifyCdt

You can update selected values in place.

Example: Increase quantity by 10 for all in-stock variants of featured products.

Java

  Expression incrementQuantity = Exp.build(
      MapExp.put(
          MapPolicy.Default,
          Exp.val("quantity"),  // key to update
          Exp.add(              // new value: current quantity + 10
              MapExp.getByKey(MapReturnType.VALUE, Exp.Type.INT,
                  Exp.val("quantity"),
                  Exp.mapLoopVar(LoopVarPart.VALUE)),
              Exp.val(10)
          ),
          Exp.mapLoopVar(LoopVarPart.VALUE)  // map to update
      )
  );

  client.operate(null, key,
      CdtOperation.modifyByPath("inventory", Exp.SELECT_MATCHING_TREE, incrementQuantity,
          CTX.allChildren(),
          CTX.allChildrenWithFilter(filterOnFeatured),
          CTX.mapKey(Value.get("variants")),
          CTX.allChildrenWithFilter(filterOnVariantInventory)
      )
  );

Python

increment_quantity = exp.Add(
    exp.MapGetByKey(
              ctx=None,
              return_type=MAP_RETURN_VALUE,
              value_type=exp.ResultType.INTEGER,
              key=exp.Val("quantity"),
              bin=exp.LoopVarMap(aerospike.EXP_LOOPVAR_VALUE)
          ),
    exp.Val(10)
).compile()

ops = [operations.modify_cdt("inventory", increment_quantity,
       cdt_ctx.all_children_with_filter(filter_on_featured)),  # only featured products
       cdt_ctx.all_children(),  # dive into variants
       cdt_ctx.all_children_with_filter(filter_on_variant_inventory)] # only in-stock variants
(key, meta, bins) = client.operate(key, ops)

Go

// Variant-level: inventory > 0
incrementQuantity := aero.ExpMapPut(
    aero.DefaultMapPolicy(),
    aero.ExpStringVal("quantity"),
    aero.ExpNumAdd(
      aero.ExpMapGetByKey(
        aero.MapReturnType.VALUE,
        aero.ExpTypeINT,
        aero.ExpStringVal("quantity"),
        aero.ExpMapLoopVar(aero.VALUE),
      ),
      aero.ExpIntVal(10),
    ),
    aero.ExpMapLoopVar(aero.VALUE),
  )

  _, err = client.Operate(nil, key,
    aero.ModifyByPath("inventory", aero.EXP_PATH_MODIFY_DEFAULT, incrementQuantity,
      aero.CtxAllChildren(),
      aero.CtxAllChildrenWithFilter(filterOnFeatured),
      aero.CtxMapKey(aero.NewValue("variants")),
      aero.CtxAllChildrenWithFilter(filterOnVariantInventory),
    ),
  )

C

// Configure our increment operation
as_exp_build(increment_quantity, as_exp_add(
    as_exp_map_get_by_key(
        NULL, AS_MAP_RETURN_VALUE,
        AS_EXP_TYPE_INT,
        as_exp_str("quantity"),
        as_exp_loopvar_map(AS_EXP_LOOPVAR_MAP_VALUE)
    ),
    as_exp_int64(10)
));
if (increment_quantity == NULL) {
    goto fail_increment_quantity;
}

// Details elided for brevity
as_exp_build(filter_on_featured, ...);
as_exp_build(filter_on_variant_inventory, ...);

// Operation

as_cdt_ctx ctx;
as_cdt_ctx_inita(&ctx, 3);
as_cdt_ctx_add_all_children_with_filter(&ctx, filter_on_featured);
as_cdt_ctx_add_all_children(&ctx),
as_cdt_ctx_add_all_children_with_filter(&ctx, filter_on_variant_inventory);

as_operations ops;
as_operations_inita(&ops, 1);
status = as_operations_modify_by_path(&err, &ops, "testbin", &ctx,
    increment_quantity,
    AS_EXP_PATH_MODIFY_NO_FAIL);
if (status != AEROSPIKE_OK) {
    goto fail_select_by_path;
}

as_record* rec = NULL;
status = aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
if (status != AEROSPIKE_OK) {
    goto fail_key_operate;
}

C#

string updatedBin = "updatedBinName";

// Increment quantity by 10 and return the modified map
Exp incrementExp = MapExp.Put(
  MapPolicy.Default,
  Exp.Val("quantity"),  // key to update
  Exp.Add(  // new value: current quantity + 10
    MapExp.GetByKey(MapReturnType.VALUE, Exp.Type.INT,
      Exp.Val("quantity"),
      Exp.MapLoopVar(LoopVarPart.VALUE)),
    Exp.Val(10)
  ),
  Exp.MapLoopVar(LoopVarPart.VALUE)
);

Expression modifyExpression = Exp.Build(
  CDTExp.ModifyByPath(
    Exp.Type.MAP,
    ModifyFlag.DEFAULT,
    incrementExp,
    Exp.MapBin("inventory"),
    CTX.AllChildren(),
    CTX.AllChildrenWithFilter(filterOnFeatured),
    CTX.MapKey(Value.Get("variants")),
    CTX.AllChildrenWithFilter(filterOnVariantInventory)
  )
);

// Write the modified map to a new bin
client.Operate(null, key,
  ExpOperation.Write(updatedBin, modifyExpression, ExpWriteFlags.DEFAULT));

// Read back the updated record
Record updatedRecord = client.Get(null, rkey);
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize((Dictionary<object, object>)updatedRecord.GetMap(updatedBin), new System.Text.Json.JsonSerializerOptions { WriteIndented = true }));

Expected output (diff excerpt):

{
  "inventory": {
    "10000001": {
      "category": "clothing",
      "featured": true,
      "name": "Classic T-Shirt",
      "description": "A lightweight cotton T-shirt perfect for everyday wear.",
      "variants": {
        "2001": { "size": "S", "price": 25, "quantity": 110 }, // 100 -> 110
        "2003": { "size": "L", "price": 27, "quantity": 60 } // 50 -> 60
      }
    },
    "50000009": {
      "category": "electronics",
      "featured": true,
      "name": "Smart TV",
      "description": "Ultra HD smart television with built-in streaming apps.",
      "variants": [
        { "sku": 3007, "spec": "1080p", "price": 199, "quantity": 70 }, // 60 -> 70
        { "sku": 3008, "spec": "4K", "price": 399, "quantity": 40 }  // 30 -> 40
      ]
    },
  }
}

✅ Inventories for in-stock variants are incremented directly on the server.

Combine multiple filters

Filters can be chained with AND / OR with each expression pulling data from the current iteration’s element into a different loop variable.

Example: Select variants that are in stock and have price < 50.

Java

  Exp filterOnCheapInStock = Exp.and(
      Exp.gt(
          MapExp.getByKey(MapReturnType.VALUE, Exp.Type.INT,
              Exp.val("quantity"),
              Exp.mapLoopVar(LoopVarPart.VALUE)),
          Exp.val(0)),
      Exp.lt(
          MapExp.getByKey(MapReturnType.VALUE, Exp.Type.INT,
              Exp.val("price"),
              Exp.mapLoopVar(LoopVarPart.VALUE)),
          Exp.val(50)));

  Record record = client.operate(null, key,
      CdtOperation.selectByPath("inventory", Exp.SELECT_MATCHING_TREE,
          CTX.allChildren(),
          CTX.allChildren(),
          CTX.mapKey(Value.get("variants")),
          CTX.allChildrenWithFilter(filterOnCheapInStock)));

Python

filter_on_cheap_in_stock = exp.And(
    exp.GT(
        exp.MapGetByKey(
          ctx=None,
          return_type=MAP_RETURN_VALUE,
          value_type=exp.ResultType.INTEGER,
          key=exp.Val("quantity"),
          bin=exp.LoopVarMap(aerospike.EXP_LOOPVAR_VALUE)
      ),
    exp.Val(0)
    ),
    exp.LT(
        exp.MapGetByKey(
          ctx=None,
          return_type=MAP_RETURN_VALUE,
          value_type=exp.ResultType.INTEGER,
          key=exp.Val("quantity"),
          bin=exp.LoopVarMap(aerospike.EXP_LOOPVAR_VALUE)
      ),
    exp.Val(50)
    )
).compile()

ops = [expression_operations.path_expression("inventory", SelectFlags.MATCHING_TREE.flag,
       cdt_ctx.all_children_with_filter(filter_on_featured)),  # only featured products
       cdt_ctx.all_children(),  # dive into variants
       cdt_ctx.all_children_with_filter(filter_on_cheap_in_stock)] # only in-stock variants
(key, meta, bins) = client.operate(key, ops)

Go

  filterOnCheapInStock := aero.ExpAnd(
    aero.ExpGreater(
      aero.ExpMapGetByKey(
        aero.MapReturnType.VALUE,
        aero.ExpTypeINT,
        aero.ExpStringVal("quantity"),
        aero.ExpMapLoopVar(aero.VALUE),
      ),
      aero.ExpIntVal(0),
    ),
    aero.ExpLess(
      aero.ExpMapGetByKey(
        aero.MapReturnType.VALUE,
        aero.ExpTypeINT,
        aero.ExpStringVal("price"),
        aero.ExpMapLoopVar(aero.VALUE),
      ),
      aero.ExpIntVal(50),
    ),
  )

  cheapInStock, err := client.Operate(nil, key,
    aero.SelectByPath("inventory", aero.EXP_PATH_SELECT_MATCHING_TREE,
      aero.CtxAllChildren(),
      aero.CtxAllChildren(),
      aero.CtxMapKey(aero.NewValue("variants")),
      aero.CtxAllChildrenWithFilter(filterOnCheapInStock),
    ),
  )

C

as_exp_build(filter_on_cheap_in_stock, as_exp_and(
    as_exp_cmp_gt(
        as_exp_map_get_by_key(
            NULL, AS_MAP_RETURN_VALUE, AS_EXP_TYPE_INT,
            as_exp_str("quantity"),
            as_exp_loopvar_map(AS_EXP_LOOPVAR_MAP_VALUE)
        ),
        as_exp_int64(0)
    ),
    as_exp_cmp_lt(
        as_exp_map_get_by_key(
            NULL, AS_MAP_RETURN_VALUE, AS_EXP_TYPE_INT,
            as_exp_str("price"),
            as_exp_loopvar_map(AS_EXP_LOOPVAR_MAP_VALUE)
        ),
        as_exp_int64(50)
    )
));
if (filter_on_cheap_in_stock == NULL) {
    goto fail_filter_on_cheap_in_stock;
}

// Details elided for brevity
as_exp_build(filter_on_featured, ...);

// Operation

as_cdt_ctx ctx;
as_cdt_ctx_inita(&ctx, 3);
as_cdt_ctx_add_all_children_with_filter(&ctx, filter_on_featured);
as_cdt_ctx_add_all_children(&ctx),
as_cdt_ctx_add_all_children_with_filter(&ctx, filter_on_cheap_in_stock);

as_operations ops;
as_operations_inita(&ops, 1);
status = as_operations_select_by_path(&err, &ops, "testbin", &ctx,
    AS_EXP_PATH_SELECT_MAP_KEY | AS_EXP_PATH_SELECT_NO_FAIL);
if (status != AEROSPIKE_OK) {
    goto fail_select_by_path;
}

as_record* rec = NULL;
status = aerospike_key_operate(&as, &err, NULL, &key, &ops, &rec);
if (status != AEROSPIKE_OK) {
    goto fail_key_operate;
}

// Print in JSON format

as_map* map = as_record_get_map(rec, "testbin");
if (map) {
    char* map_str = as_val_tostring((as_val*)map);
    log("%s\n", map_str);
    free(map_str);
} else {
    log("No data returned\n");
}

C#

Exp filterOnCheapInStock = Exp.And(
  Exp.GT(
    MapExp.GetByKey(MapReturnType.VALUE, Exp.Type.INT,
      Exp.Val("quantity"),
      Exp.MapLoopVar(LoopVarPart.VALUE)
    ),
    Exp.Val(0)
  ),
  Exp.LT(
    MapExp.GetByKey(MapReturnType.VALUE, Exp.Type.INT,
      Exp.Val("price"),
      Exp.MapLoopVar(LoopVarPart.VALUE)
    ),
    Exp.Val(50)
  )
);

// Operation
Record record = client.Operate(null, rkey,
  CDTOperation.SelectByPath(inventoryBinName, SelectFlag.MATCHING_TREE,
    CTX.AllChildren(), // navigate into all products
    CTX.AllChildren(), // navigate deeper into product structure
    CTX.MapKey(Value.Get("variants")), // navigate into variants map/list
    CTX.AllChildrenWithFilter(filterOnCheapInStock) // filter variants bt price and quantity
  )
);
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize((Dictionary<object, object>)record.GetMap("inventory"), new System.Text.Json.JsonSerializerOptions { WriteIndented = true }));

Expected output:

{
  "inventory": {
    "10000001": {
      "category": "clothing",
      "featured": true,
      "name": "Classic T-Shirt",
      "description": "A lightweight cotton T-shirt perfect for everyday wear.",
      "variants": {
        "2001": { "size": "S", "price": 25, "quantity": 100 },
        "2003": { "size": "L", "price": 27, "quantity": 50}
      }
    }
  }
}

✅ Only items are returned which have price < 50 and quantity > 0.

❌ Item 10000002, Casual Polo Shirt, excluded (featured=false).

❌ Item 50000006, Laptop Pro 14, excluded (quantity=0).

❌ Item 50000009, Smart TV, both variants excluded (price > 50).

NO_FAIL: tolerate malformed product

If we add this item to the inventory bin:

"10000003": {
  "category": "clothing",
  "featured": true,
  "name": "Hooded Sweatshirt",
  "description": "Warm fleece hoodie with front pocket and adjustable hood.",
  "variants": "no variant"
}

The dataset now includes item 10000003 with variants: “no variant” (a string). Any traversal that reaches variants and then tries to treat it as a Map/List will hit a type mismatch and throw an error unless SelectFlags.NO_FAIL.flag is set.

Java

Record noFailResponse = client.operate(null, key,
      CdtOperation.selectByPath("inventory", Exp.SELECT_MATCHING_TREE | Exp.SELECT_NO_FAIL,
          CTX.allChildren(),
          CTX.allChildrenWithFilter(filterOnFeatured),
          CTX.mapKey(Value.get("variants")),
          CTX.allChildrenWithFilter(filterOnVariantInventory)
      )
);

C

as_operations ops;
as_operations_inita(&ops, 1);
status = as_operations_select_by_path(&err, &ops, "testbin", &ctx,
    AS_EXP_PATH_SELECT_MAP_KEY | AS_EXP_PATH_SELECT_NO_FAIL);
if (status != AEROSPIKE_OK) {
    goto fail_select_by_path;
}

or

as_operations ops;
as_operations_inita(&ops, 1);
status = as_operations_modify_by_path(&err, &ops, "testbin", &ctx,
    modification_expression,
    AS_EXP_PATH_MODIFY_NO_FAIL);
if (status != AEROSPIKE_OK) {
    goto fail_select_by_path;
}

Python

ops = [expression_operations.path_expression("inventory", aerospike.EXP_PATH_SELECT_MATCHING_TREE | aerospike.EXP_PATH_SELECT_NO_FAIL,
       cdt_ctx.all_children_with_filter(filter_on_featured)),
       cdt_ctx.all_children(),
       cdt_ctx.all_children_with_filter(filter_on_variant_inventory)]
(key, meta, bins) = client.operate(key, ops)

print(bins["inventory"])

Go

// Operation
record, err := client.Operate(nil, key,
  aero.SelectByPath("inventory", aero.EXP_PATH_SELECT_MATCHING_TREE|aero.EXP_PATH_SELECT_NO_FAIL,
    aero.CtxAllChildren(),
    aero.CtxAllChildrenWithFilter(filterOnFeatured),
    aero.CtxMapKey(aero.NewValue("variants")),
    aero.CtxAllChildrenWithFilter(filterOnVariantInventory),
  ),
)

C#

Record noFailResponse = client.Operate(null, key,
  CDTOperation.SelectByPath(inventoryBinName, SelectFlag.MATCHING_TREE | SelectFlag.NO_FAIL,
    CTX.AllChildren(),
    CTX.AllChildrenWithFilter(filterOnFeatured),
    CTX.MapKey(Value.Get("variants")),
    CTX.AllChildrenWithFilter(filterOnVariantInventory)
  )
);
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize((Dictionary<object, object>)noFailResponse.GetMap("inventory"), new System.Text.Json.JsonSerializerOptions { WriteIndented = true }));

• malformed_product.variants is “no variant”.

• With NO_FAIL, malformed_product is excluded silently because variants was “no variant”.

Expected output:

Same as the corresponding non-NO_FAIL query, omitting any items from malformed_product.

{
  "inventory": {
    "10000001": {
      "category": "clothing",
      "featured": true,
      "name": "Classic T-Shirt",
      "description": "A lightweight cotton T-shirt perfect for everyday wear.",
      "variants": {
        "2001": { "size": "S", "price": 25, "quantity": 100 },
        "2003": { "size": "L", "price": 27, "quantity": 50
        }
      }
    },
    "50000009": {
      "category": "electronics",
      "featured": true,
      "name": "Smart TV",
      "description": "Ultra HD smart television with built-in streaming apps.",
      "variants": [
        { "sku": 3007, "spec": "1080p", "price": 199, "quantity": 60 },
        { "sku": 3008, "spec": "4K", "price": 399, "quantity": 30 }
      ]
    }
  }
}

❌ Item 10000003 skipped silently because variants was a string.

Handle errors gracefully

Path Expression operations can fail for several reasons. Always wrap operations in error handling to provide a good user experience.

Common error scenarios:

• Target bin doesn’t exist or isn’t a CDT
• Type mismatch in filter expression (without NO_FAIL)
• Server timeout during complex traversals

Java

import com.aerospike.client.AerospikeException;
import com.aerospike.client.ResultCode;

try {
  client.operate(null, key,
      CdtOperation.selectByPath("inventory", Exp.SELECT_MATCHING_TREE,
          CTX.allChildren(),
          CTX.allChildrenWithFilter(filterOnFeatured),
          CTX.mapKey(Value.get("variants")),
          CTX.allChildrenWithFilter(filterOnVariantInventory)));
} catch (AerospikeException e) {
  switch (e.getResultCode()) {
    case ResultCode.OP_NOT_APPLICABLE:
      // The bin exists but isn't a Map or List - can't traverse it
      System.err.println("Bin is not a Map or List");
      break;
    case ResultCode.PARAMETER_ERROR:
       // The filter expression is malformed or uses wrong types
       System.err.println("Invalid expression in filter");
      break;
    default:
        // Unexpected error (network, timeout, etc.) - propagate it
        throw e;
  }
}

Python

import aerospike
from aerospike import exception as aero_exception

try:
    # Execute the path expression operation
    (key, meta, bins) = client.operate(key, ops)
    # Success - process the filtered results
    print(bins["inventory"])

except aero_exception.OpNotApplicable as e:
    # The bin exists but isn't a Map or List - can't traverse it
    print(f"Bin is not a Map or List: {e}")

except aero_exception.InvalidRequest as e:
    # The filter expression is malformed or uses wrong types
    print(f"Invalid expression in filter: {e}")

except aero_exception.AerospikeError as e:
    # Unexpected error (network, timeout, etc.) - propagate it
    raise

Go

// Execute the path expression operation

  _, err = client.Operate(nil, key,
    aero.SelectByPath("inventory", aero.EXP_PATH_SELECT_MATCHING_TREE,
      aero.CtxAllChildren(),
      aero.CtxAllChildrenWithFilter(filterOnFeatured),
      aero.CtxMapKey(aero.NewValue("variants")),
      aero.CtxAllChildrenWithFilter(filterOnVariantInventory),
    ),
  )

// Check for errors and handle specific cases
if err != nil {
    // Type assert to access Aerospike-specific error details
    if aeroErr, ok := err.(*aero.AerospikeError); ok {
        switch aeroErr.ResultCode {
        case types.OP_NOT_APPLICABLE:
            // The bin exists but isn't a Map or List - can't traverse it
            log.Println("Bin is not a Map or List")
        case types.PARAMETER_ERROR:
            // The filter expression is malformed or uses wrong types
            log.Println("Invalid expression in filter")
        default:
            // Unexpected error (network, timeout, etc.) - propagate it
            return err
        }
    }
}

// Success - process the filtered results
fmt.Println(record.Bins["inventory"])

C

// ...
as_operations ops;
as_operations_inita(&ops, 1);
status = as_operations_modify_by_path(&err, &ops, "testbin", &ctx,
    modification_expression,
    AS_EXP_PATH_MODIFY_NO_FAIL);
if (status != AEROSPIKE_OK) {
    // if-then-switch is commonly used to avoid delays in hot-path
    // code, as different compilers will likely optimize switch statements
    // to varying degrees, especially depending upon how sparse the cases
    // are.  This way, switch overhead is incurred only when an error is
    // known to have occurred.
    switch (status) {
    case AEROSPIKE_ERR_OP_NOT_APPLICABLE:
        fprintf(stderr, "Bin is not a Map or List");
        break;

    case AEROSPIKE_ERR_PARAMETER_ERROR:
        fprintf(stderr, "Invalid expression in filter");
        break;

    case AEROSPIKE_ERR_TIMEOUT:
        fprintf(stderr, "Server is taking too long");
        break;

    default:
        // Note that the status is also available within the as_error
        // structure, as member code.
        fprintf(stderr,
            "Unknown error: code %d\n"
            "                msg %s\n",
            err.code,
            err.message
        );
        break;
    }
}

C#

try
{
  client.Operate(null, rkey,
    CDTOperation.SelectByPath(
      inventoryBinName, SelectFlag.MATCHING_TREE,
      CTX.AllChildren(),
      CTX.AllChildrenWithFilter(filterOnFeatured),
      CTX.MapKey(Value.Get("variants")),
      CTX.AllChildrenWithFilter(filterOnVariantInventory)
    )
  );
}
catch (AerospikeException e)
{
  switch (e.Result)
  {
    case ResultCode.OP_NOT_APPLICABLE:
      // The bin exists but isn't a Map or List - can't traverse it
      Console.WriteLine("Bin is not a Map or List");
      break;
    case ResultCode.PARAMETER_ERROR:
      // The filter expression is malformed or uses wrong types
      Console.WriteLine("Invalid expression in filter");
      break;

    default:
      // Unexpected error (network, timeout, etc.) - propagate it
      throw;
  }
}

Tip

Use NO_FAIL for resilience. If your data may contain malformed records, combine error handling with SelectFlags.NO_FAIL to skip problematic elements while still catching true operational errors.