apache/cassandra · error · InvalidRequestException

ANN ordering is only supported on float vector indexes

Error message

ANN ordering is only supported on float vector indexes

What it means

Thrown when an ANN (ORDER BY col ANN OF [...]) restriction targets a column that is not a vector<float, n> type. Vector similarity search is only implemented for float element vectors; other element types (or non-vector columns) cannot be used for ANN ordering.

Source

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

            if (!type.allowNonPrimaryKeyInWhereClause())
            {
                Collection<ColumnIdentifier> nonPrimaryKeyColumns =
                        ColumnMetadata.toIdentifiers(nonPrimaryKeyRestrictions.columns());

                throw invalidRequest("Non PRIMARY KEY columns found in where clause: %s ",
                                     Joiner.on(", ").join(nonPrimaryKeyColumns));
            }

            Optional<SingleRestriction> annRestriction = Streams.stream(nonPrimaryKeyRestrictions)
                                                                .filter(SingleRestriction::isANN)
                                                                .findFirst();
            if (annRestriction.isPresent())
            {
                // If there is an ANN restriction then it must be for a vector<float, n> column, and it must have an index
                ColumnMetadata annColumn = annRestriction.get().firstColumn();

                if (!annColumn.type.isVector() || !(((VectorType<?>)annColumn.type).elementType instanceof FloatType))
                    throw invalidRequest(ANN_ONLY_SUPPORTED_ON_VECTOR_MESSAGE);
                if (indexRegistry == null || indexRegistry.listIndexes().stream().noneMatch(i -> i.dependsOn(annColumn)))
                    throw invalidRequest(ANN_REQUIRES_INDEX_MESSAGE);
                // We do not allow ANN queries using partition key restrictions that need filtering
                if (partitionKeyRestrictions.needFiltering())
                    throw invalidRequest(ANN_REQUIRES_INDEXED_FILTERING_MESSAGE);
                // We do not allow ANN query filtering using non-indexed columns
                List<ColumnMetadata> nonAnnColumns = Streams.stream(nonPrimaryKeyRestrictions)
                                                            .filter(r -> !r.isANN())
                                                            .map(SingleRestriction::firstColumn)
                                                            .collect(Collectors.toList());
                List<ColumnMetadata> clusteringColumns = clusteringColumnsRestrictions.columns();
                if (!nonAnnColumns.isEmpty() || !clusteringColumns.isEmpty())
                {
                    List<ColumnMetadata> nonIndexedColumns = Stream.concat(nonAnnColumns.stream(), clusteringColumns.stream())
                                                                   .filter(c -> indexRegistry.listIndexes().stream().noneMatch(i -> i.dependsOn(c)))
                                                                   .collect(Collectors.toList());
                    if (!nonIndexedColumns.isEmpty())
                    {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Use a vector<float, n> column for ANN queries; recreate/alter the column to vector<float, n> if needed.
2. Point the ORDER BY ... ANN clause at the actual float vector column in the table.
3. For non-float embeddings, convert them to float arrays before storage, or use a different search mechanism (full scan + client-side similarity).
4. Verify the column type via DESCRIBE TABLE before issuing ANN queries.

Example fix

// before
CREATE TABLE t (k int PRIMARY KEY, v vector<int, 3>); -- ANN unsupported
// after
CREATE TABLE t (k int PRIMARY KEY, v vector<float, 3>);

ColumnMetadata col = table.getColumn(annColumn);
if (!(col.getType() instanceof VectorType) || !(((VectorType<?>) col.getType()).getElementType() instanceof FloatType))
    throw new IllegalArgumentException("ANN requires a vector<float, n> column");

boolean isFloatVector(DataType t) { return t instanceof VectorType && ((VectorType<?>) t).getElementType() instanceof FloatType; }

When it happens

Trigger: `SELECT * FROM t ORDER BY v ANN OF [0.1,0.2]` where v is vector<int, n>, vector<double, ...>, or a non-vector column; table created with a non-float vector element type then queried with ANN.

Common situations: Schema designed with integer or binary embeddings; copy-pasted ANN queries against the wrong column; upgrade/migration where vector type changed.

Related errors

• Cannot specify more than one ANN ordering
• ANN ordering does not support any other ordering
• Descending ANN ordering is not supported
• %s cannot be restricted by more than one relation in an ANN
• Function %s requires a %s vector argument, but found argumen

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