Cassandra Asks for ALLOW FILTERING on a Clustering Key? Here's Why

You defined PRIMARY KEY ((tenant_id), created_at, event_id). event_id is a clustering key, so querying WHERE tenant_id = ? AND event_id = ? should be fast, right? Instead Cassandra replies: Cannot execute this query as it might involve data filtering and thus may have unpredictable performance. If you want to execute this query despite the performance unpredictability, use ALLOW FILTERING. On older clusters the message is different: PRIMARY KEY column "event_id" cannot be restricted as preceding column "created_at" is not restricted. Both mean the same thing, and the reason is how Cassandra stores rows on disk.

How Clustering Columns Are Stored

Inside a partition, Cassandra stores rows sorted by the clustering columns in the order you declared them. With PRIMARY KEY ((tenant_id), created_at, event_id), rows are sorted by created_at first, then by event_id within each created_at.

That sort order is what makes reads fast: Cassandra can seek to an exact created_at, then to an exact event_id within it. It can't seek to an event_id on its own, because event_ids are scattered across every created_at.

CREATE TABLE tenant_events (
    tenant_id  text,
    created_at date,
    event_id   text,
    payload    text,
    PRIMARY KEY ((tenant_id), created_at, event_id)
);
-- Within a tenant, rows are sorted by created_at, then event_id

The Query That Triggers It

Restricting event_id without created_at skips the first clustering column. Cassandra would have to read the whole partition and filter rows, so it refuses unless you opt in.

-- Skips created_at, the first clustering column
SELECT * FROM tenant_events
WHERE tenant_id = 't-9921' AND event_id = 'evt_88320';

-- Cassandra 3.6+:
-- InvalidRequest: Cannot execute this query as it might involve data filtering
-- and thus may have unpredictable performance. If you want to execute this query
-- despite the performance unpredictability, use ALLOW FILTERING

-- Cassandra before 3.6:
-- PRIMARY KEY column "event_id" cannot be restricted as preceding column
-- "created_at" is not restricted

The Rules for Clustering Columns

For a query Cassandra can serve without filtering:

1. Restrict every partition key column with = (or IN).
2. Restrict clustering columns from the left, without gaps.
3. Use = on all of them except the last one you restrict, which may use a range (<, >, <=, >=).

A range on created_at followed by a restriction on event_id breaks rule 3, and so does any gap.

-- Uses both clustering columns in order: direct read
SELECT * FROM tenant_events
WHERE tenant_id = 't-9921'
  AND created_at = '2026-11-05'
  AND event_id = 'evt_88320';

-- Range on the last restricted clustering column: also fine
SELECT * FROM tenant_events
WHERE tenant_id = 't-9921'
  AND created_at >= '2026-11-01' AND created_at < '2026-11-06';

When ALLOW FILTERING Is Acceptable

ALLOW FILTERING doesn't make the query faster; it just lets it run. Its cost depends on how much data must be read:

• With the full partition key: Cassandra reads only that partition and filters it. Acceptable when partitions are small and bounded.
• Without the partition key: Cassandra scans data across the whole cluster. Avoid in application code; it degrades as data grows and can time out.

Fixes That Avoid Filtering

Pick based on how often the query runs:

1. Supply the missing column, if the caller knows it.
2. Reorder the clustering key so the column you query by comes first, if that's the main access pattern.
3. Add a query table: Cassandra data modelling is query-first, so a second table keyed for this lookup is the standard answer. Write to both, usually in a logged batch.
4. Use an index: Storage-Attached Indexing (SAI, in Cassandra 5.0 and DataStax Astra) or a secondary index can serve some lookups, best within a partition. Materialized views exist but are experimental and disabled by default since Cassandra 4.0.

CREATE TABLE tenant_events_by_id (
    tenant_id  text,
    event_id   text,
    created_at date,
    payload    text,
    PRIMARY KEY ((tenant_id), event_id)
);

SELECT * FROM tenant_events_by_id
WHERE tenant_id = 't-9921' AND event_id = 'evt_88320';