QueryHint¶

class aerospike_sdk.aio.operations.query.QueryHint[source]¶

Bases: object

Hint for influencing secondary index selection and query scheduling.

Provide index_name as a soft explain hint on the server-led path. To bypass server-led selection and choose the access path yourself, attach an explicit index filter with QueryBuilder.filter() instead.

On clusters that support field 44 query selection (>= 8.2.0), allow_scans_with_where and hard_hint set Tier-D WHERE flags on explain. allow_scans_with_where is tri-state: None inherits the Behavior setting (by default the primary-index fallback is allowed), True allows the fallback for this query, False rejects it.

Example:

hint = QueryHint(
    index_name="age_idx",
    query_duration=QueryDuration.SHORT,
)
stream = await (
    session.query(dataset)
        .where("$.age > 30")
        .with_hint(hint)
        .execute()
)

Parameters:

index_name (Optional[str]) – Soft index name hint (field 21 on explain).
query_duration (Optional[QueryDuration]) – Override expected_duration on the query policy.
allow_scans_with_where (Optional[bool]) – Tri-state override for whether a where-clause query may fall back to a primary-index scan. None (default) inherits the Behavior; True allows the fallback, False rejects it (sets REQUIRE_INDEX on explain).
hard_hint (bool) – Explain flag — require index_name to be selected.

Raises:

ValueError – If hard_hint is set without index_name.