apache/cassandra · error · InvalidRequestException

%s cannot be restricted by more than one relation in an ANN

Error message

%s cannot be restricted by more than one relation in an ANN ordering

What it means

Cassandra rejects an ANN (approximate nearest neighbor) ORDER BY query when the ANN column has more than one restriction relation attached. ANN search requires exactly one ordering relation per restricted column, so MergedRestriction.checkOperator throws this InvalidRequest at query validation time before execution.

Source

Thrown at src/java/org/apache/cassandra/cql3/restrictions/MergedRestriction.java:187

                throw invalidRequest("More than one restriction was found for the end bound on %s",
                                     toCQLString(getColumnsInCommons(restriction, other)));
            }
        }
    }

    private static void checkOperator(SimpleRestriction restriction)
    {
        if (restriction.isColumnLevel() || restriction.isOnToken())
        {
            if (restriction.isEQ())
                throw invalidRequest("%s cannot be restricted by more than one relation if it includes an Equal",
                                      toCQLString(restriction.columns()));

            if (restriction.isIN())
                throw invalidRequest("%s cannot be restricted by more than one relation if it includes a IN",
                                     toCQLString(restriction.columns()));
            if (restriction.isANN())
                throw invalidRequest("%s cannot be restricted by more than one relation in an ANN ordering",
                                     toCQLString(restriction.columns()));
        }
    }

    /**
     * Returns the columns that are specified within the 2 {@code Restrictions}.
     *
     * @param restriction the first restriction
     * @param other the other restriction
     * @return the columns that are specified within the 2 {@code Restrictions}.
     */
    private static Set<ColumnMetadata> getColumnsInCommons(Restriction restriction, Restriction other)
    {
        Set<ColumnMetadata> commons = new HashSet<>(restriction.columns());
        commons.retainAll(other.columns());
        return commons;
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Keep exactly one restriction relation on the ANN-ordered column
2. Move filtering of the vector column out of the ANN restriction set and use ALLOW FILTERING or a secondary index for other predicates
3. Rewrite the query so the vector column appears only in the ANN ORDER BY clause

Example fix

// before
SELECT * FROM t WHERE v : [1,2] AND v : [1,2] ORDER BY v ANN OF [1,2];
// after
SELECT * FROM t WHERE id = 5 ORDER BY v ANN OF [1,2];

// client-side before building query
if (restrictionsOn(annColumn).length > 1) throw new Error("ANN column must have exactly one relation");

catch (InvalidRequestException e) { if (e.getMessage().contains("ANN ordering")) fixQueryPlan(); }

When it happens

Trigger: Issuing a SELECT with 'ORDER BY col ANN OF [..]' where col is also restricted by multiple relations (e.g. merged from a multicolumn restriction or duplicate WHERE clauses on the same column).

Common situations: Building vector-search queries programmatically and appending duplicate relations on the vector column; combining a secondary restriction with ANN ordering in the same restriction set.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot specify more than one ANN ordering
• ANN ordering does not support any other ordering
• Descending ANN ordering is not supported
• ANN ordering is only supported on float vector indexes
• Unsupported expression during ANN index query:

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