apache/cassandra · error · InvalidRequestException

Vector indexes only support ANN queries

Error message

Vector indexes only support ANN queries

What it means

A vector column that has an index may only be queried via ANN ordering; Cassandra does not support indexed vector restrictions outside of ORDER BY ... ANN OF. If a WHERE restriction touches an indexed vector column without an ANN ordering clause, StatementRestrictions throws this error.

Solutions

1. Rewrite the query as an ANN search: SELECT ... ORDER BY embedding ANN OF [1,2,3] LIMIT n
2. Remove the vector column restriction if similarity ranking is not needed
3. Drop the vector index if exact-match filtering on the vector is truly required (requires ALLOW FILTERING and full scan)

Example fix

// before
SELECT id FROM items WHERE embedding = [0.1, 0.2, 0.3];
// after
SELECT id FROM items ORDER BY embedding ANN OF [0.1, 0.2, 0.3] LIMIT 10;

// Reject vector restrictions without ANN ordering before sending:
if (where.contains(vectorColumn) && !orderBy.contains(vectorColumn + " ANN OF")) throw new IllegalArgumentException("Use ANN ordering for indexed vector column");

When it happens

Trigger: SELECT * FROM t WHERE embedding = [1,2,3] (or similar vector restriction) on a column with a vector index, without ORDER BY embedding ANN OF [...]; also using vector comparisons like >= on an indexed vector column.

Common situations: Porting SQL-style exact-match vector queries to Cassandra; expecting vector equality filtering after creating a vector index; mixing similarity search syntax from other databases.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• ANN ordering does not support any other ordering
• Cannot specify more than one ANN ordering
• Descending ANN ordering is not supported
• ACCESS TO DATACENTERS operations not supported by…
• aggregate functions cannot be used as arguments of…

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

Appendix: source

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

                    if (!nonIndexedColumns.isEmpty())
                    {
                        // restrictions on non-clustering columns, or clusterings that still need filtering, are invalid
                        if (!clusteringColumns.containsAll(nonIndexedColumns)
                                || partitionKeyRestrictions.hasUnrestrictedPartitionKeyComponents()
                                || clusteringColumnsRestrictions.needFiltering())
                            throw invalidRequest(StatementRestrictions.ANN_REQUIRES_INDEXED_FILTERING_MESSAGE);
                    }
                }
            }
            else
            {
                // We do not support indexed vector restrictions that are not part of an ANN ordering
                Optional<ColumnMetadata> vectorColumn = nonPrimaryKeyRestrictions.columns()
                                                                                 .stream()
                                                                                 .filter(c -> c.type.isVector())
                                                                                 .findFirst();
                if (vectorColumn.isPresent() && indexRegistry.listIndexes().stream().anyMatch(i -> i.dependsOn(vectorColumn.get())))
                    throw invalidRequest(StatementRestrictions.VECTOR_INDEXES_ANN_ONLY_MESSAGE);
            }

            if (hasQueriableIndex)
            {
                usesSecondaryIndexing = true;
            }
            else
            {
                if (!allowFiltering && requiresAllowFilteringIfNotSpecified(table, false))
                    throw invalidRequest(allowFilteringMessage(state));
            }

            filterRestrictions.add(nonPrimaryKeyRestrictions);
        }

        if (usesSecondaryIndexing)
            validateSecondaryIndexSelections();
    }

View on GitHub (pinned to 88fd0f6a0e)