Filter Generation

Filter generation from AEL expressions.

This module provides functionality to generate optimal secondary index Filters from AEL expressions based on available indexes. It splits expressions to use secondary indexes where possible and filter expressions for the rest.

The implementation uses a tree-based approach: 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

class aerospike_sdk.ael.filter_gen.IndexTypeEnum

Bases: Enum

Index type for filter generation matching.

INTEGER is the preferred name for an integer-valued index — that is the wording used by the Aerospike server from version 8.1.2 onward and by other Aerospike SDKs. NUMERIC is retained as a back-compat alias that maps to the same wire type and is interchangeable with INTEGER in to_aerospike().

NUMERIC = 'NUMERIC'

INTEGER = 'INTEGER'

STRING = 'STRING'

GEO2D_SPHERE = 'GEO2D_SPHERE'

BLOB = 'BLOB'

to_aerospike()

Convert to aerospike_async IndexType.

Return type:

IndexType

class aerospike_sdk.ael.filter_gen.Index

Bases: object

Represents an Aerospike secondary index.

namespace

Namespace of the indexed bin.

bin

Name of the indexed bin.

index_type

Type of the index (NUMERIC, STRING, GEO2D_SPHERE).

name

Optional name of the index.

bin_values_ratio

Cardinality ratio (entries_per_bval). Higher = more selective. Used to choose optimal index when multiple are available.

collection_index_type

Collection index type for list/map indexes.

ctx

Array of CTX representing context of the index.

set_name

Aerospike set this index is defined on, when known. None means the index is not bound to a specific set (cross-set / null set). Blank strings are normalized to None.

bin: str

index_type: IndexTypeEnum

namespace: str | None = None

name: str | None = None

bin_values_ratio: float | None = None

collection_index_type: CollectionIndexType | None = None

ctx: List[CTX] | None = None

set_name: str | None = None

__init__(bin, index_type, namespace=None, name=None, bin_values_ratio=None, collection_index_type=None, ctx=None, set_name=None)

class aerospike_sdk.ael.filter_gen.IndexContext

Bases: object

Holds namespace and indexes for filter generation.

namespace

Namespace to match with index namespaces.

indexes

Collection of Index objects for filter generation.

query_set

Aerospike set name for the current query. When set, the filter generator restricts secondary-index selection to indexes whose Index.set_name matches (or is unset, i.e. a cross-set index). When None or blank, no set-based filtering applies. Blank strings are normalized to None.

namespace: str

indexes: List[Index]

query_set: str | None = None

classmethod of(namespace, indexes)

Create IndexContext with namespace and indexes.

Return type:

IndexContext

classmethod with_query_set(namespace, query_set, indexes)

Create IndexContext that restricts index selection to query_set.

Indexes whose Index.set_name is None (cross-set) remain eligible regardless of query_set.

Return type:

IndexContext

static index_matches_query_set(index, query_set)

Whether index is eligible for filter selection under query_set.

Returns True when query_set is None (no filtering), the index has no set name (cross-set), or the index’s set name equals query_set. Mirrors the semantics used by reference clients so cross-set indexes remain shared by per-set queries.

Return type:

bool

__init__(namespace, indexes=<factory>, query_set=None)

class aerospike_sdk.ael.filter_gen.ParseResult

Bases: object

Result of parsing an AEL expression with filter generation.

Contains both a secondary index Filter (if applicable) and a filter Exp (for remaining expression parts that can’t use secondary indexes).

filter

Secondary index Filter. None if no applicable index found.

exp

Filter expression for remaining parts. None if fully covered by filter.

filter: Filter | None

exp: FilterExpression | None

__init__(filter, exp)

class aerospike_sdk.ael.filter_gen.OperationType

Bases: Enum

Expression operation types.

AND = 'AND'

OR = 'OR'

EQ = 'EQ'

NE = 'NE'

GT = 'GT'

GE = 'GE'

LT = 'LT'

LE = 'LE'

NOT = 'NOT'

class aerospike_sdk.ael.filter_gen.ExpressionNode

Bases: object

A node in the expression tree.

Tracks filter eligibility for secondary index selection.

op: OperationType

left: ExpressionNode | None = None

right: ExpressionNode | None = None

bin_name: str | None = None

value: Any = None

value_type: IndexTypeEnum | None = None

bin_explicit_type: str | None = None

ctx: List[CTX] | None = None

has_secondary_index_filter: bool = False

is_excl_from_secondary_index_filter: bool = False

ael_fragment: str | None = None

arith_op: str | None = None

arith_constant: int | None = None

bin_on_left: bool | None = None

__init__(op, left=None, right=None, bin_name=None, value=None, value_type=None, bin_explicit_type=None, ctx=None, has_secondary_index_filter=False, is_excl_from_secondary_index_filter=False, ael_fragment=None, arith_op=None, arith_constant=None, bin_on_left=None)

class aerospike_sdk.ael.filter_gen.FilterGenerator

Bases: object

Generates optimal Filter from an AEL expression based on available indexes.

The generator analyzes the expression tree to find parts that can use secondary indexes, choosing the most selective index based on cardinality. Parts that can’t use secondary indexes remain as filter expressions.

__init__(index_context=None)

Initialize with optional index context.

generate(ael_string, placeholder_values=None, *, hint_index_name=None, hint_bin_name=None)

Generate Filter and Exp from an AEL expression string.

Parameters:

• ael_string (str) – The AEL expression string.

• placeholder_values (Any) – Optional placeholder values.

• hint_index_name (Optional[str]) – If set, the generated Filter uses a _by_index variant keyed to this index name instead of the bin name.

• hint_bin_name (Optional[str]) – If set, the generated Filter addresses this bin name instead of the one found in the AEL expression.

Return type:

ParseResult

Returns:

ParseResult with Filter and/or Exp.