IndexBuilder¶

class aerospike_sdk.aio.operations.index.IndexBuilder[source]¶

Bases: _IndexBuilderBase

Configure a secondary index, then create() or drop() it.

Typical chain for a new index: on_bin() → named() → integer() or string() → optional collection() or context() → await create(). Expression-based indexes replace on_bin() with on_expression(); a set index is just on_set() → named() → await create().

For removal, only named() (and namespace/set from construction) is required before await drop().

Example:

users = DataSet.of("test", "users")
await (
    session.index(users)
    .on_bin("email")
    .named("email_idx")
    .string()
    .create()
)

See also

index()

__init__(client, namespace, set_name)[source]¶

Parameters:

client (Client) – Connected SDK client; admin calls dispatch through its underlying PNC client, and AEL-string chains read its server-capability gate.
namespace (str) – Namespace containing the set to index.
set_name (str) – Set name within the namespace.

async create()[source]¶

Create the index on the cluster.

The server builds the index asynchronously, so the returned task is how you know when it is usable: a query through an index that is still building can miss records that are already written.

Example:

task = await (
    session.index(users)
    .on_bin("email")
    .named("email_idx")
    .string()
    .create()
)
await task.wait_till_complete()

Return type:

IndexTask

Returns:

An IndexTask tracking the server-side build. Await wait_till_complete() before querying through the index.

Raises:

ValueError – If on_bin (or on_expression / on_set), named, or index type was not set, or if mutually exclusive chain methods were combined.
AerospikeError – On server or transport failure (typed subclass when the driver maps a result code).

See also

drop()

async drop()[source]¶

Drop a previously created index by name.

Example:

task = await (
    session.index(users)
    .named("email_idx")
    .drop()
)
await task.wait_till_complete()

Return type:

DropIndexTask

Returns:

A DropIndexTask tracking the server-side removal.

Raises:

ValueError – If named() was not called.
AerospikeError – On server or transport failure.

Note

Namespace and set come from the builder constructor, not from on_bin().

blob()¶

Set the secondary index type to blob (for bytes bin values).

Call this before create() to index a bin containing raw bytes values for exact-match query.

Return type:: Self
Returns:: self for method chaining.

collection(collection_index_type)¶

Set the collection index variant for map or list bins (optional).

Use together with integer() or string() when indexing into collection data types.

Parameters:: collection_index_type (CollectionIndexType) – CollectionIndexType constant from the aerospike_native package (map- vs list-style collection indexing).
Return type:: Self
Returns:: self for method chaining.

context(ctx)¶

Set a CDT context path for indexing a nested list or map element.

Parameters:: ctx (List[CTX]) – One or more CTX entries describing the path to the nested element (e.g., [CTX.map_key("outer"), CTX.list_index(0)]).
Return type:: Self
Returns:: self for method chaining.

Example:

events = DataSet.of("test", "events")
await (
    session.index(events)
    .on_bin("payload")
    .named("nested_ts_idx")
    .integer()
    .context([CTX.map_key("meta"), CTX.map_key("timestamp")])
    .create()
)

See also

context(): Attach the same path when querying.

geo2dsphere()¶

Set the secondary index type to GEO2DSPHERE (for GeoJSON bin values).

Call this before create() to index a bin containing GeoJSON Points, Polygons, or AeroCircles for spatial query via geoCompare(...).

Return type:: Self
Returns:: self for method chaining.

integer()¶

Set the secondary index type to integer (for integer bin values).

Call this or string() before create(), matching how the bin is stored. If both are called on the same builder, the last call wins. The server calls this index type integer; the SDK sends that name.

Return type:: Self
Returns:: self for method chaining.

named(index_name)¶

Set the secondary index name the cluster stores (required for create and drop).

Parameters:: index_name (str) – Name passed to create/drop admin calls; must match when dropping.
Return type:: Self
Returns:: self for method chaining.

on_bin(bin_name)¶

Set which bin this secondary index covers (required before create()).

Parameters:: bin_name (str) – Name of the bin to index.
Return type:: Self
Returns:: self for method chaining.
Raises:: ValueError – If on_set() was already called on this builder.

on_expression(expression)¶

Index the value an expression computes per record, instead of a bin.

The expression is evaluated server-side for every record in the set; its result becomes the indexed value. The expression’s result type must match the index type set via integer(), string(), or geo2dsphere() — a boolean predicate is rejected by the server, so build a value-producing expression (e.g. via FilterExpression.cond).

An AEL string may be passed instead of a prebuilt expression; the server parses and compiles it when the index is created, so the cluster must support server-compiled AEL (server 8.2.0 or newer on every node) or create() raises with result code OP_NOT_APPLICABLE.

Mutually exclusive with on_bin() — an index covers either a bin or an expression, never both. Not combinable with context() (encode CDT navigation inside the expression instead).

Parameters:

expression (Union[str, FilterExpression]) – A prebuilt FilterExpression whose result is the value to index, or an AEL string for the server to compile.

Return type:

Self

Returns:

self for method chaining.

Raises:

TypeError – If expression is neither an AEL string nor a FilterExpression.
ValueError – If on_bin() was already called on this builder.

Example:

from aerospike_sdk.exp import Exp

users = DataSet.of("test", "users")
adult_flag = Exp.cond([
    Exp.ge(Exp.int_bin("age"), Exp.int_val(18)),
    Exp.int_val(1),
    Exp.unknown(),
])
await (
    session.index(users)
    .on_expression(adult_flag)
    .named("users_adult_idx")
    .integer()
    .create()
)

# Or let the server compile an AEL string (server 8.2.0+):
await (
    session.index(users)
    .on_expression("$.age + 1")
    .named("users_age_ael_idx")
    .integer()
    .create()
)

See also

on_bin(): Index a plain bin value.

on_set()¶

Index record presence in the set itself, rather than a bin or expression.

A set index covers every record in the set and nothing about their contents, so it takes no bin, index type, collection variant, or CDT context: the chain is on_set() → named() → create(). Creating one needs only the sindex-admin privilege. The builder must name a set; a namespace-wide set index is rejected.

Mutually exclusive with on_bin() and on_expression().

Return type:: Self
Returns:: self for method chaining.
Raises:: ValueError – If on_bin() or on_expression() was already called on this builder.

Example:

users = DataSet.of("test", "users")
task = await (
    session.index(users)
    .on_set()
    .named("users_set_idx")
    .create()
)
await task.wait_till_complete()

See also

on_bin(): Index a bin value. on_expression(): Index a value an expression computes.

string()¶

Set the secondary index type to string (for string bin values).

Call this or integer() before create(). If both are called, the last call wins (see integer()).

Return type:: Self
Returns:: self for method chaining.