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.

NUMERIC = 'NUMERIC'

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.

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

__init__(bin, index_type, namespace=None, name=None, bin_values_ratio=None, collection_index_type=None, ctx=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.

namespace: str

indexes: List[Index]

classmethod of(namespace, indexes)

Create IndexContext with namespace and indexes.

Return type:

IndexContext

__init__(namespace, indexes=<factory>)

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.