{"record":{"id":"e648e6c8460cb3e9","repo":"apache/cassandra","slug":"use-of-ann-of-in-an-order-by-clause-requires-a-lim","errorCode":null,"errorMessage":"Use of ANN OF in an ORDER BY clause requires a LIMIT that is not greater than %s. LIMIT was %s","messagePattern":"Use of ANN OF in an ORDER BY clause requires a LIMIT that is not greater than (.+?)\\. LIMIT was (.+?)","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java","lineNumber":539,"sourceCode":"        return (leftBuf, rightBuf) -> {\n            float[] left = indexTermType.decomposeVector(leftBuf.duplicate());\n            double scoreLeft = function.compare(left, target);\n\n            float[] right = indexTermType.decomposeVector(rightBuf.duplicate());\n            double scoreRight = function.compare(right, target);\n            return Double.compare(scoreRight, scoreLeft); // descending order\n        };\n    }\n\n    @Override\n    public void validate(ReadCommand command) throws InvalidRequestException\n    {\n        if (!indexTermType.isVector())\n            return;\n\n        // to avoid overflow of the vector graph internal data structure and avoid OOM when filtering top-k\n        if (command.limits().count() > MAX_TOP_K)\n            throw new InvalidRequestException(String.format(ANN_LIMIT_ERROR, MAX_TOP_K, command.limits().count()));\n    }\n\n    @Override\n    public long getEstimatedResultRows()\n    {\n        throw new UnsupportedOperationException(\"Use StorageAttachedIndexQueryPlan#getEstimatedResultRows() instead.\");\n    }\n\n    @Override\n    public boolean isQueryable(Status status)\n    {\n        // consider unknown status as queryable, because gossip may not be up-to-date for newly joining nodes.\n        return status == Status.BUILD_SUCCEEDED || status == Status.UNKNOWN;\n    }\n\n    @Override\n    public void validate(PartitionUpdate update, ClientState state) throws InvalidRequestException\n    {","sourceCodeStart":521,"sourceCodeEnd":557,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sai/StorageAttachedIndex.java#L521-L557","documentation":"ANN (vector) queries limit top-K to MAX_TOP_K to protect the vector graph data structure from overflow and OOM during top-k filtering. StorageAttachedIndex.validate checks the command's LIMIT; if limits().count() exceeds MAX_TOP_K it throws this InvalidRequestException with the allowed maximum and the actual LIMIT.","triggerScenarios":"Executing a SELECT with ORDER BY <vector_col> ANN OF [...] and LIMIT n where n > MAX_TOP_K (e.g., LIMIT 2000 when the cap is 1000).","commonSituations":"Bulk similarity search scripts requesting large result pages; application pagination implemented by raising LIMIT; default page sizes tuned for non-ANN queries.","solutions":["Reduce the LIMIT of the ANN ORDER BY query to <= MAX_TOP_K.","Issue multiple ANN queries with per-partition filters to distribute the top-k across queries.","Retrieve more results by narrowing the search space (e.g., additional WHERE filters) rather than a larger LIMIT."],"exampleFix":"// before\nSELECT ... FROM ks.tbl ORDER BY embedding ANN OF [0.1,...] LIMIT 5000;\n// after\nSELECT ... FROM ks.tbl ORDER BY embedding ANN OF [0.1,...] LIMIT 1000;","handlingStrategy":"validation","validationCode":"const MAX_TOP_K = 1000; if (query.orderBy?.type === 'ANN' && query.limit > MAX_TOP_K) throw new Error(`ANN LIMIT must be <= ${MAX_TOP_K}`);","typeGuard":null,"tryCatchPattern":"catch (InvalidRequestException e) { if (e.getMessage().startsWith('Use of ANN OF in an ORDER BY clause requires a LIMIT')) { // clamp limit to the reported maximum and retry } }","preventionTips":["Clamp ANN query LIMITs to the documented MAX_TOP_K","Do not use ANN queries for bulk exports","Parse the allowed maximum from the error message before retrying"],"tags":["cassandra","sai","vector","ann","limit"],"backgroundTag":"value-out-of-range","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"}