{"record":{"id":"1ad0c6d119706dcf","repo":"apache/cassandra","slug":"the-key-column-can-only-be-used-in-an-equality-q","errorCode":null,"errorMessage":"The 'key' column can only be used in an equality query for this virtual table.","messagePattern":"The 'key' column can only be used in an equality query for this virtual table\\.","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/db/virtual/PartitionKeyStatsTable.java","lineNumber":315,"sourceCode":"            if (!slice.start().isEmpty())\n            {\n                startTokenValue = startTokenValue.min(IntegerType.instance.compose(slice.start().bufferAt(0)));\n                startToken = target.partitioner.getTokenFactory().fromString(startTokenValue.toString());\n            }\n            if (!slice.end().isEmpty())\n            {\n                endTokenValue = endTokenValue.max(IntegerType.instance.compose(slice.end().bufferAt(0)));\n                endToken = target.partitioner.getTokenFactory().fromString(endTokenValue.toString());\n            }\n        }\n\n        // override min/max of token if the `key` is specified\n        for (RowFilter.Expression expression : rowFilter.getExpressions())\n        {\n            if (expression.column().name.toString().equals(COLUMN_KEY))\n            {\n                if (expression.operator() != Operator.EQ)\n                    throw new InvalidRequestException(KEY_ONLY_EQUALS_ERROR);\n\n                String keyString = UTF8Type.instance.compose(expression.getIndexValue());\n                ByteBuffer keyAsBB;\n                try\n                {\n                    keyAsBB = target.partitionKeyType.fromString(keyString);\n                }\n                catch (MarshalException ex)\n                {\n                    throw new InvalidRequestException(ex.getMessage());\n                }\n                DecoratedKey decoratedKey = target.partitioner.decorateKey(keyAsBB);\n\n                if (!DataRange.forKeyRange(new Range<>(startToken.minKeyBound(), endToken.maxKeyBound())).contains(decoratedKey.getToken().minKeyBound()))\n                    throw new InvalidRequestException(KEY_NOT_WITHIN_BOUNDS_ERROR);\n\n                return Bounds.bounds(decoratedKey, true, decoratedKey, true);\n            }","sourceCodeStart":297,"sourceCodeEnd":333,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/db/virtual/PartitionKeyStatsTable.java#L297-L333","documentation":"On the system_views.partitions virtual table, the 'key' column may only be filtered with an equality operator. getBounds() inspects row filter expressions and throws InvalidRequestException if 'key' appears with anything other than EQ (e.g. IN, CONTAINS, range operators).","triggerScenarios":"`SELECT ... FROM system_views.partitions WHERE key > '...'`, `key IN (...)`, or any non-equality restriction on the 'key' column combined with token/partition constraints.","commonSituations":"Users assuming 'key' behaves like a normal indexed column supporting ranges; tooling generating generic WHERE clauses; attempts to enumerate a subset of partitions via key ranges.","solutions":["Use strict equality on 'key': `WHERE key = '<partition key value>'`.","To scan multiple partitions, filter by token range instead (without 'key'), e.g. `WHERE token(...) > ... AND token(...) < ...`.","Update generated queries/ORM filters so 'key' is only EQ."],"exampleFix":"// before\nSELECT * FROM system_views.partitions WHERE keyspace_name='ks' AND table_name='t' AND key > 'pk1';\n// after\nSELECT * FROM system_views.partitions WHERE keyspace_name='ks' AND table_name='t' AND key = 'pk1';","handlingStrategy":"validation","validationCode":"// Only EQ on 'key' is allowed\nif (whereClauseColumn.equals(\"key\") && !operator.equals(\"=\"))\n    throw new IllegalArgumentException(\"'key' supports only equality on system_views.partitions\");","typeGuard":null,"tryCatchPattern":"try { rs = session.execute(query); }\ncatch (com.datastax.oss.driver.api.core.servererrors.InvalidQueryException e) {\n    if (e.getMessage().contains(\"can only be used in an equality query\")) { /* rewrite with key = ... */ }\n    else throw e;\n}","preventionTips":["Use only `key = <literal>` filters on the partitions virtual table.","Use token ranges (without key) for multi-partition scans.","Do not let generic query builders apply IN/>/</CONTAINS to 'key'."],"tags":["cassandra","virtual-table","query","filtering"],"backgroundTag":"invalid-query-parameter","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"}