apache/cassandra · error · InvalidRequestException

The 'key' column can only be used in an equality query for t

Error message

The 'key' column can only be used in an equality query for this virtual table.

What it means

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).

Source

Thrown at src/java/org/apache/cassandra/db/virtual/PartitionKeyStatsTable.java:315

            if (!slice.start().isEmpty())
            {
                startTokenValue = startTokenValue.min(IntegerType.instance.compose(slice.start().bufferAt(0)));
                startToken = target.partitioner.getTokenFactory().fromString(startTokenValue.toString());
            }
            if (!slice.end().isEmpty())
            {
                endTokenValue = endTokenValue.max(IntegerType.instance.compose(slice.end().bufferAt(0)));
                endToken = target.partitioner.getTokenFactory().fromString(endTokenValue.toString());
            }
        }

        // override min/max of token if the `key` is specified
        for (RowFilter.Expression expression : rowFilter.getExpressions())
        {
            if (expression.column().name.toString().equals(COLUMN_KEY))
            {
                if (expression.operator() != Operator.EQ)
                    throw new InvalidRequestException(KEY_ONLY_EQUALS_ERROR);

                String keyString = UTF8Type.instance.compose(expression.getIndexValue());
                ByteBuffer keyAsBB;
                try
                {
                    keyAsBB = target.partitionKeyType.fromString(keyString);
                }
                catch (MarshalException ex)
                {
                    throw new InvalidRequestException(ex.getMessage());
                }
                DecoratedKey decoratedKey = target.partitioner.decorateKey(keyAsBB);

                if (!DataRange.forKeyRange(new Range<>(startToken.minKeyBound(), endToken.maxKeyBound())).contains(decoratedKey.getToken().minKeyBound()))
                    throw new InvalidRequestException(KEY_NOT_WITHIN_BOUNDS_ERROR);

                return Bounds.bounds(decoratedKey, true, decoratedKey, true);
            }

View on GitHub (pinned to 88fd0f6a0e)

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.

Example fix

// before
SELECT * FROM system_views.partitions WHERE keyspace_name='ks' AND table_name='t' AND key > 'pk1';
// after
SELECT * FROM system_views.partitions WHERE keyspace_name='ks' AND table_name='t' AND key = 'pk1';

Defensive patterns

Strategy: validation

Validate before calling

// Only EQ on 'key' is allowed
if (whereClauseColumn.equals("key") && !operator.equals("="))
    throw new IllegalArgumentException("'key' supports only equality on system_views.partitions");

Try / catch

try { rs = session.execute(query); }
catch (com.datastax.oss.driver.api.core.servererrors.InvalidQueryException e) {
    if (e.getMessage().contains("can only be used in an equality query")) { /* rewrite with key = ... */ }
    else throw e;
}

Prevention

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'.

When it happens

Trigger: `SELECT ... FROM system_views.partitions WHERE key > '...'`, `key IN (...)`, or any non-equality restriction on the 'key' column combined with token/partition constraints.

Common situations: 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.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

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