AEL Parser

AEL parser — parse Aerospike Expression Language text into FilterExpression objects.

This module provides parsing of text-based AEL expressions like:

“$.country == ‘US’ and $.order_total > 500”

into Aerospike FilterExpression objects.

Supports parameterized queries with placeholders:

parse_ael(“$.age > ?0”, 30)

Also supports parsing paths into CTX arrays:

parse_ctx(“$.listBin.[0].[1]”) # Returns [CTX.list_index(0), CTX.list_index(1)]

Also supports filter generation with index context:

parse_ael_with_index(“$.intBin1 > 100 and $.intBin2 < 50”, index_context) # Returns ParseResult with optimal Filter + remaining Exp

class aerospike_sdk.ael.parser.PlaceholderValues

Bases: object

Internal container for placeholder values (?0, ?1, …) in AEL queries.

Not part of the public API — use parse_ael() with *args instead.

__init__(*values)

get(index)

Return type:

Any

class aerospike_sdk.ael.parser.AELParser

Bases: object

Parser for Aerospike Expression Language (AEL) text.

static parse(expression, placeholder_values=None)

Parse an AEL expression string into a FilterExpression.

Parameters:

• expression (str) – The AEL expression string (e.g., “$.country == ‘US’ and $.order_total > 500”)

• placeholder_values (Optional[PlaceholderValues]) – Optional values for placeholders (?0, ?1, etc.)

Return type:

FilterExpression

Returns:

A FilterExpression object that can be used in queries.

Raises:

AelParseException – If the expression cannot be parsed.

aerospike_sdk.ael.parser.parse_ael(expression, *args)

Parse an AEL expression string into a FilterExpression.

Convenience function that uses a global parser instance.

Parameters:

• expression (str) – The AEL expression string.

• *args (Any) – Values for placeholders ?0, ?1, ?2, etc.

Return type:

FilterExpression

Returns:

A FilterExpression object.

Example

expr = parse_ael(“$.age > 30”) expr = parse_ael(“$.age > ?0 and $.name == ?1”, 30, “John”)

aerospike_sdk.ael.parser.parse_ctx(path)

Parse an AEL path into a list of CTX objects.

Converts an AEL path like “$.listBin.[0].[1]” into a CTX array for use with secondary index context operations.

Parameters:

path (str) – The AEL path string (e.g., “$.listBin.[0]”, “$.mapBin.key.subkey”)

Return type:

List[CTX]

Returns:

A list of CTX objects representing the path context.

Raises:

AelParseException – If the path is invalid or unsupported.

Example

ctx = parse_ctx(“$.listBin.[0].[1]”) # Returns [CTX.list_index(0), CTX.list_index(1)]

ctx = parse_ctx(“$.mapBin.a.bb”) # Returns [CTX.map_key(“a”), CTX.map_key(“bb”)]

aerospike_sdk.ael.parser.parse_ael_with_index(expression, index_context=None, placeholder_values=None, *, hint_index_name=None, hint_bin_name=None)

Parse an AEL expression and generate optimal Filter + Exp based on available indexes.

This function analyzes the AEL expression and available secondary indexes to: 1. Extract parts that can use secondary index Filters (more efficient) 2. Return remaining parts as filter Exp (for post-filtering)

The algorithm: 1. Build an expression tree that tracks filter eligibility 2. Mark nodes under OR as “excluded from filter” (can’t use secondary index) 3. Collect all filterable expressions grouped by cardinality 4. Choose the best by cardinality (or alphabetically if tied) 5. Generate complementary Exp, skipping the part used for Filter

Rules for filter generation: - AND expressions: One part can become Filter, rest becomes Exp - OR expressions: Cannot use Filter (need to evaluate both branches) - Nested AND inside OR: The AND parts are still excluded - AND(a, OR(b, c)): ‘a’ can become Filter, OR(b,c) becomes Exp - Only simple comparisons (==, >, <, >=, <=) on indexed bins can become Filters - String comparisons (>, <, etc.) are not supported by secondary index

Parameters:

• expression (str) – The AEL expression string.

• index_context (Optional[IndexContext]) – IndexContext with available indexes. If None, only Exp is returned.

• placeholder_values (Optional[Sequence[Any]]) – Optional sequence of values for placeholders (?0, ?1, etc.)

• hint_index_name (Optional[str]) – Force the generated Filter to target this named secondary index via Filter.\*_by_index().

• hint_bin_name (Optional[str]) – Override the bin name used for the generated Filter.

Returns:

• filter: Secondary index Filter (or None if not applicable)

• exp: Filter expression for remaining parts (or None if fully covered)

Return type:

ParseResult

Example:

Build an :class:`~aerospike_sdk.ael.filter_gen.IndexContext` with
:class:`~aerospike_sdk.ael.filter_gen.Index` entries (see ``filter_gen``),
then pass it as *index_context*::

    ctx = IndexContext.of("test", [...])
    result = parse_ael_with_index("$.intBin1 > 100 and $.intBin2 < 1000", ctx)
    result = parse_ael_with_index("$.intBin1 > ?0", ctx, (100,))