What causes "Cannot specify more than one ANN ordering" in apache/cassandra?

Keep only one ANN ordering clause in the ORDER BY.

apache/cassandra · error · InvalidRequestException

Cannot specify more than one ANN ordering

Error message

Cannot specify more than one ANN ordering

What it means

ANN (approximate nearest neighbor) vector similarity ordering is restricted to a single ORDER BY clause: at most one ANN ordering may appear per query. addOrderingRestrictions rejects queries with more than one vector-similarity ordering expression.

Source

Thrown at src/java/org/apache/cassandra/cql3/restrictions/StatementRestrictions.java:549

    public boolean usesSecondaryIndexing()
    {
        return this.usesSecondaryIndexing;
    }

    /**
     * This is a hack to push ordering down to indexes.
     * Indexes are selected based on RowFilter only, so we need to turn orderings into restrictions
     * so they end up in the row filter.
     *
     * @param orderings orderings from the select statement
     * @return the {@link RestrictionSet} with the added orderings
     */
    private RestrictionSet addOrderingRestrictions(List<Ordering> orderings, RestrictionSet restrictionSet)
    {
        List<Ordering> annOrderings = orderings.stream().filter(o -> o.expression.hasNonClusteredOrdering()).collect(Collectors.toList());

        if (annOrderings.size() > 1)
            throw new InvalidRequestException("Cannot specify more than one ANN ordering");
        else if (annOrderings.size() == 1)
        {
            if (orderings.size() > 1)
                throw new InvalidRequestException("ANN ordering does not support any other ordering");
            Ordering annOrdering = annOrderings.get(0);
            if (annOrdering.direction != Ordering.Direction.ASC)
                throw new InvalidRequestException("Descending ANN ordering is not supported");
            SingleRestriction restriction = annOrdering.expression.toRestriction();
            return restrictionSet.addRestriction(restriction);
        }
        return restrictionSet;
    }

    private void processPartitionKeyRestrictions(ClientState state, boolean hasQueriableIndex, boolean allowFiltering, boolean forView)
    {
        if (!type.allowPartitionKeyRanges())
        {
            checkFalse(partitionKeyRestrictions.isOnToken(),

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Keep only one ANN ordering clause in the ORDER BY.
Run separate queries per vector and merge/rank the results client-side.
Combine vectors into a single embedding if a joint similarity is really intended.

Example fix

// before
SELECT * FROM items ORDER BY ann_of(vec1) : [0.1,0.2], ann_of(vec2) : [0.3,0.4];
// after
SELECT * FROM items ORDER BY ann_of(vec1) : [0.1,0.2]; // run a second query for vec2

Defensive patterns

Strategy: validation

Validate before calling

long annCount = orderings.stream().filter(o -> o.hasNonClusteredOrdering()).count();
if (annCount > 1) throw new IllegalArgumentException("only one ANN ordering allowed");

Try / catch

try { session.execute(stmt); }
catch (InvalidRequestException e) {
    if (e.getMessage().equals("Cannot specify more than one ANN ordering")) { /* split into multiple queries */ }
    else throw e;
}

Prevention

Document that vector search supports one ANN ordering per query.
Do multi-vector ranking in application code.
Validate ORDER BY construction helpers to emit at most one ANN term.

When it happens

Trigger: A SELECT ... ORDER BY ann_of(v) : [0.1,0.2], ... with two or more ANN ordering expressions on vector columns in one statement.

Common situations: Attempting multi-vector similarity search (e.g. order by similarity to two different query vectors) directly in one CQL query on a vector-enabled (SAI/vector search) table.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/0ee75328bfb0f14a. Report an issue: GitHub.