{"record":{"id":"a57721fefcdabdc6","repo":"apache/cassandra","slug":"vector-indexes-only-support-ann-queries","errorCode":null,"errorMessage":"Vector indexes only support ANN queries","messagePattern":"Vector indexes only support ANN queries","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/restrictions/StatementRestrictions.java","lineNumber":367,"sourceCode":"                    if (!nonIndexedColumns.isEmpty())\n                    {\n                        // restrictions on non-clustering columns, or clusterings that still need filtering, are invalid\n                        if (!clusteringColumns.containsAll(nonIndexedColumns)\n                                || partitionKeyRestrictions.hasUnrestrictedPartitionKeyComponents()\n                                || clusteringColumnsRestrictions.needFiltering())\n                            throw invalidRequest(StatementRestrictions.ANN_REQUIRES_INDEXED_FILTERING_MESSAGE);\n                    }\n                }\n            }\n            else\n            {\n                // We do not support indexed vector restrictions that are not part of an ANN ordering\n                Optional<ColumnMetadata> vectorColumn = nonPrimaryKeyRestrictions.columns()\n                                                                                 .stream()\n                                                                                 .filter(c -> c.type.isVector())\n                                                                                 .findFirst();\n                if (vectorColumn.isPresent() && indexRegistry.listIndexes().stream().anyMatch(i -> i.dependsOn(vectorColumn.get())))\n                    throw invalidRequest(StatementRestrictions.VECTOR_INDEXES_ANN_ONLY_MESSAGE);\n            }\n\n            if (hasQueriableIndex)\n            {\n                usesSecondaryIndexing = true;\n            }\n            else\n            {\n                if (!allowFiltering && requiresAllowFilteringIfNotSpecified(table, false))\n                    throw invalidRequest(allowFilteringMessage(state));\n            }\n\n            filterRestrictions.add(nonPrimaryKeyRestrictions);\n        }\n\n        if (usesSecondaryIndexing)\n            validateSecondaryIndexSelections();\n    }","sourceCodeStart":349,"sourceCodeEnd":385,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/restrictions/StatementRestrictions.java#L349-L385","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Rewrite the query as an ANN search: SELECT ... ORDER BY embedding ANN OF [1,2,3] LIMIT n","Remove the vector column restriction if similarity ranking is not needed","Drop the vector index if exact-match filtering on the vector is truly required (requires ALLOW FILTERING and full scan)"],"exampleFix":"// before\nSELECT id FROM items WHERE embedding = [0.1, 0.2, 0.3];\n// after\nSELECT id FROM items ORDER BY embedding ANN OF [0.1, 0.2, 0.3] LIMIT 10;","handlingStrategy":"validation","validationCode":"// Reject vector restrictions without ANN ordering before sending:\nif (where.contains(vectorColumn) && !orderBy.contains(vectorColumn + \" ANN OF\")) throw new IllegalArgumentException(\"Use ANN ordering for indexed vector column\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always express vector lookups as ORDER BY col ANN OF [...] LIMIT n","Never use =/>=/<= on indexed vector columns","Keep a query lint rule banning vector columns in plain WHERE clauses"],"tags":["cql","vector-search","cassandra"],"backgroundTag":"unsupported-operation","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}