apache/cassandra · error · ConfigurationException

partition key columns are not yet supported by SASI

Error message

partition key columns are not yet supported by SASI

What it means

SASI refuses partition key columns as index targets. The partition key is already stored in the SSTable key and token layout, so indexing it provides no benefit; validateOptions checks target.left.isPartitionKey() and throws this ConfigurationException.

Source

Thrown at src/java/org/apache/cassandra/index/sasi/SASIIndex.java:171

     */
    public static Map<String, String> validateOptions(Map<String, String> options, TableMetadata metadata)
    {
        if (!(metadata.partitioner instanceof Murmur3Partitioner))
            throw new ConfigurationException("SASI only supports Murmur3Partitioner.");

        String targetColumn = options.get("target");
        if (targetColumn == null)
            throw new ConfigurationException("unknown target column");

        Pair<ColumnMetadata, IndexTarget.Type> target = TargetParser.parse(metadata, targetColumn);
        if (target == null)
            throw new ConfigurationException("failed to retrieve target column for: " + targetColumn);

        if (target.left.isComplex())
            throw new ConfigurationException("complex columns are not yet supported by SASI");

        if (target.left.isPartitionKey())
            throw new ConfigurationException("partition key columns are not yet supported by SASI");

        IndexMode.validateAnalyzer(options, target.left);

        IndexMode mode = IndexMode.getMode(target.left, options);
        if (mode.mode == Mode.SPARSE)
        {
            if (mode.isLiteral)
                throw new ConfigurationException("SPARSE mode is only supported on non-literal columns.");

            if (mode.isAnalyzed)
                throw new ConfigurationException("SPARSE mode doesn't support analyzers.");
        }

        return Collections.emptyMap();
    }

    @Override
    public void register(IndexRegistry registry)

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Remove the index creation on the partition key column; query by partition key directly instead.
2. If fuzzy matching on a key-like column is needed, store the value in a duplicate non-key column and index that with SASI.
3. Restrict automated index generation to non-key columns.

Example fix

// before (user_id is the partition key)
CREATE CUSTOM INDEX ON users (user_id) USING 'org.apache.cassandra.index.sasi.SASIIndex';
// after: query by the partition key directly, or index a copy
CREATE CUSTOM INDEX ON users (user_id_text) USING 'org.apache.cassandra.index.sasi.SASIIndex'
  WITH OPTIONS = {'target': 'user_id_text', 'mode': 'PREFIX'};

// skip partition key columns when auto-generating indexes
ColumnMetadata col = tableMetadata.getColumn(targetName);
if (col.isPartitionKey()) throw new IllegalArgumentException("Do not index partition key column " + targetName);

try {
    session.execute(createIndexStmt);
} catch (InvalidQueryException e) {
    if (e.getMessage().contains("partition key columns are not yet supported")) { /* skip or duplicate column */ }
}

When it happens

Trigger: Creating a SASI index whose 'target' option resolves to a column that is part of the table's PRIMARY KEY partition key (the first key column(s)).

Common situations: Script-generated indexes applied to every column of a table; developers trying to speed up partition-key lookups with SASI without realizing partition keys are directly queryable.

Related errors

• unknown target column
• failed to retrieve target column for: %s
• Key may not be empty
• Key length of %d is longer than maximum of %d
• allowFilteringMessage(state)

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