{"record":{"id":"8e577fbebd06965f","repo":"apache/cassandra","slug":"ann-ordering-is-only-supported-on-float-vector-ind","errorCode":null,"errorMessage":"ANN ordering is only supported on float vector indexes","messagePattern":"ANN ordering is only supported on float vector indexes","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/restrictions/StatementRestrictions.java","lineNumber":332,"sourceCode":"            if (!type.allowNonPrimaryKeyInWhereClause())\n            {\n                Collection<ColumnIdentifier> nonPrimaryKeyColumns =\n                        ColumnMetadata.toIdentifiers(nonPrimaryKeyRestrictions.columns());\n\n                throw invalidRequest(\"Non PRIMARY KEY columns found in where clause: %s \",\n                                     Joiner.on(\", \").join(nonPrimaryKeyColumns));\n            }\n\n            Optional<SingleRestriction> annRestriction = Streams.stream(nonPrimaryKeyRestrictions)\n                                                                .filter(SingleRestriction::isANN)\n                                                                .findFirst();\n            if (annRestriction.isPresent())\n            {\n                // If there is an ANN restriction then it must be for a vector<float, n> column, and it must have an index\n                ColumnMetadata annColumn = annRestriction.get().firstColumn();\n\n                if (!annColumn.type.isVector() || !(((VectorType<?>)annColumn.type).elementType instanceof FloatType))\n                    throw invalidRequest(ANN_ONLY_SUPPORTED_ON_VECTOR_MESSAGE);\n                if (indexRegistry == null || indexRegistry.listIndexes().stream().noneMatch(i -> i.dependsOn(annColumn)))\n                    throw invalidRequest(ANN_REQUIRES_INDEX_MESSAGE);\n                // We do not allow ANN queries using partition key restrictions that need filtering\n                if (partitionKeyRestrictions.needFiltering())\n                    throw invalidRequest(ANN_REQUIRES_INDEXED_FILTERING_MESSAGE);\n                // We do not allow ANN query filtering using non-indexed columns\n                List<ColumnMetadata> nonAnnColumns = Streams.stream(nonPrimaryKeyRestrictions)\n                                                            .filter(r -> !r.isANN())\n                                                            .map(SingleRestriction::firstColumn)\n                                                            .collect(Collectors.toList());\n                List<ColumnMetadata> clusteringColumns = clusteringColumnsRestrictions.columns();\n                if (!nonAnnColumns.isEmpty() || !clusteringColumns.isEmpty())\n                {\n                    List<ColumnMetadata> nonIndexedColumns = Stream.concat(nonAnnColumns.stream(), clusteringColumns.stream())\n                                                                   .filter(c -> indexRegistry.listIndexes().stream().noneMatch(i -> i.dependsOn(c)))\n                                                                   .collect(Collectors.toList());\n                    if (!nonIndexedColumns.isEmpty())\n                    {","sourceCodeStart":314,"sourceCodeEnd":350,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/restrictions/StatementRestrictions.java#L314-L350","documentation":"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.","triggerScenarios":"`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.","commonSituations":"Schema designed with integer or binary embeddings; copy-pasted ANN queries against the wrong column; upgrade/migration where vector type changed.","solutions":["Use a vector<float, n> column for ANN queries; recreate/alter the column to vector<float, n> if needed.","Point the ORDER BY ... ANN clause at the actual float vector column in the table.","For non-float embeddings, convert them to float arrays before storage, or use a different search mechanism (full scan + client-side similarity).","Verify the column type via DESCRIBE TABLE before issuing ANN queries."],"exampleFix":"// before\nCREATE TABLE t (k int PRIMARY KEY, v vector<int, 3>); -- ANN unsupported\n// after\nCREATE TABLE t (k int PRIMARY KEY, v vector<float, 3>);","handlingStrategy":"validation","validationCode":"ColumnMetadata col = table.getColumn(annColumn);\nif (!(col.getType() instanceof VectorType) || !(((VectorType<?>) col.getType()).getElementType() instanceof FloatType))\n    throw new IllegalArgumentException(\"ANN requires a vector<float, n> column\");","typeGuard":"boolean isFloatVector(DataType t) { return t instanceof VectorType && ((VectorType<?>) t).getElementType() instanceof FloatType; }","tryCatchPattern":null,"preventionTips":["Standardize embeddings on vector<float, n> columns.","Validate column types in DAO initialization.","Document that ANN is float-vector only."],"tags":["cql","ann","vector","vector-search"],"backgroundTag":"unsupported-dtype","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}