apache/cassandra · error · InvalidRequestException

Descending ANN ordering is not supported

Error message

Descending ANN ordering is not supported

What it means

InvalidRequestException from addOrderingRestrictions: an ANN (approximate nearest neighbor / vector similarity) ordering was specified as DESC. Vector similarity search ordering is inherently ascending-only, so a descending ANN ORDER BY is rejected while translating orderings into restrictions for the row filter.

Source

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

     * 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(),
                       "The token function cannot be used in WHERE clauses for %s statements", type);

            if (partitionKeyRestrictions.hasUnrestrictedPartitionKeyComponents())
                throw invalidRequest("Some partition key parts are missing: %s",
                                     Joiner.on(", ").join(getPartitionKeyUnrestrictedComponents()));

            // slice query

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Drop the DESC keyword; ANN ordering must be ASC (or defaulted).
2. If farthest-first ordering is needed, fetch ANN results and reverse/filter them client-side.
3. Use a different similarity metric/vector encoding if the intended semantics differ.

Example fix

// before
SELECT * FROM items ORDER BY ann_of(vec) : [0.1,0.2] DESC;
// after
SELECT * FROM items ORDER BY ann_of(vec) : [0.1,0.2];

if (annOrdering != null && annOrdering.direction == Direction.DESC)
    throw new IllegalArgumentException("ANN ordering must be ASC");

try { session.execute(stmt); }
catch (InvalidRequestException e) {
    if (e.getMessage().equals("Descending ANN ordering is not supported")) { /* retry with ASC */ }
    else throw e;
}

When it happens

Trigger: A SELECT with ORDER BY ann_of(vector_column) : [...] DESC on a vector-enabled table.

Common situations: Developers assume DESC gives 'most distant first' or copy DESC from other ORDER BY clauses; ANN always returns nearest neighbors, so only ASC is accepted.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Cannot specify more than one ANN ordering
• ANN ordering does not support any other ordering
• Unsupported expression during ANN index query:
• %s cannot be restricted by more than one relation in an ANN
• ANN ordering is only supported on float vector indexes

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