Frequently asked questions

Q: What does the selectFlags parameter do, and what options are available?

A: The selectFlags parameter controls what the server returns from a path expression.

Possible values are:

Value	Description
`MATCHING_TREE`	Return a tree from the root (bin) level to the bottom of the tree, with only non-filtered out nodes.
`VALUE`	Return a list of the values of the nodes finally selected by the context.
`MAP_KEY`	For final selected nodes which are elements of maps, return the appropriate map key.
`MAP_KEY_VALUE`	Return a list of key-value pairs.
`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.

Q: Can I use path expressions on both Maps and Lists?

A: Yes. CTX.allChildren and CTX.allChildrenWithFilter work across both maps and lists. Loop variables (MAP_KEY, VALUE, LIST_INDEX) allow filters to adapt depending on whether the container is a map of entries or a list of elements.

Q: What kind of exception will I see on the client if I don’t use NO_FAIL? Is it recoverable or will the whole operation abort?

A: Without SelectFlags.NO_FAIL, if the server encounters a type mismatch (e.g., it expects a map or list but finds a string), the entire path expression operation fails. The operation does not return partial results.

Q: How do I return only certain pieces of data, such as only the variant IDs?

A: The SelectFlags parameter controls return modes. For example, MATCHING_TREE returns the full subtree, MAP_KEY returns only keys, and VALUE returns only values. Choose the mode that matches your use case.

Q: Can path expressions be combined with secondary indexes?

A: Yes. A path expression can be combined with an expression index to support indexing and querying into a nested document. See the expression index example in querying collection data types.

Q: What limitations exist for using mapKeysIn in a path expression context?

A: The overarching rule is: you can only have one expression at any level. Exp.and(exp1, exp2) counts as one expression, since combining conditions is fine.

The specific consequences for MAP_KEYS_IN and AND_FILTER (introduced in 8.1.2) are:

AND_FILTER cannot be chained after another AND_FILTER (use Exp.and(...) to combine conditions into a single AND_FILTER instead).
AND_FILTER cannot be used after an ALL_CHILDREN or ALL_CHILDREN_WITH_FILTER context (those already carry an expression).
MAP_KEYS_IN and AND_FILTER are supported only with direct CDT operations (CdtOperation.selectByPath / CdtOperation.modifyByPath). They are not supported inside expression-wrapped operations (CdtExp.selectByPath).

Despite these constraints, multiple mapKeysIn + andFilter pairs can be chained at successive nesting levels in a single selectByPath call. The following example selects a top-level key, filters on a field inside it, then selects inner keys and filters again at that deeper level.

Data (stored in bin "doc"):

{
  "100": {
    "beta": 2.0,
    "1001": { "a": 1, "b": 2, "yes": 1 },
    "1002": { "z": 26 },
    "1003": { "f": 6 }
  },
  "200": {
    "beta": 3.0,
    "2001": { "d": 4, "e": 5, "yes": 1 },
    "2002": { "y": 25 }
  }
}

Chained mapKeysIn / andFilter query (Java):

Exp betaGtZero = Exp.gt(
    MapExp.getByKey(MapReturnType.VALUE, Exp.Type.FLOAT,
        Exp.val("beta"),
        Exp.mapLoopVar(LoopVarPart.VALUE)),
    Exp.val(0.0));

Exp saysYes = Exp.eq(
    MapExp.getByKey(MapReturnType.VALUE, Exp.Type.INT,
        Exp.val("yes"),
        Exp.mapLoopVar(LoopVarPart.VALUE)),
    Exp.val(1));

Operation op = CdtOperation.selectByPath("doc",
    SelectFlags.MATCHING_TREE | SelectFlags.NO_FAIL,
    CTX.mapKeysIn("100"),              // level 1: select top-level key
    CTX.andFilter(betaGtZero),         // level 1: keep only if beta > 0
    CTX.mapKeysIn("1001", "1002"),     // level 2: select inner keys
    CTX.andFilter(saysYes));           // level 2: keep only if yes == 1

Record record = client.operate(null, key, op);

Result:

{ "100": { "1001": { "a": 1, "b": 2, "yes": 1 } } }

Key "100" passes the first andFilter (its beta is 2.0 > 0). Of the two inner keys requested ("1001", "1002"), only "1001" passes the second andFilter (it has "yes": 1).

For full details on context types see the context types reference.