apache/cassandra · error · ConfigurationException

complex columns are not yet supported by SASI

Error message

complex columns are not yet supported by SASI

What it means

SASI cannot index complex columns — collections (map, set, list), UDTs, or other non-scalar cells. Once TargetParser resolves the target, validateOptions rejects any target whose ColumnMetadata.isComplex() is true with this ConfigurationException.

Source

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

    /**
     * Called via reflection at {@link IndexMetadata#validateCustomIndexOptions}
     */
    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();
    }

View on GitHub (pinned to 88fd0f6a0e)

Solutions

  1. Move the indexed value into a dedicated scalar column (e.g. denormalize the map value into a text column) and index that.
  2. Index only scalar (non-collection, non-UDT) columns with SASI.
  3. If collection search is required, use a different mechanism (e.g. a separate lookup table or an external search system).

Example fix

// before
CREATE CUSTOM INDEX ON users (tags) USING 'org.apache.cassandra.index.sasi.SASIIndex'; // tags is set<text>
// after: index a scalar projection instead
CREATE CUSTOM INDEX ON users (primary_tag) USING 'org.apache.cassandra.index.sasi.SASIIndex'
  WITH OPTIONS = {'target': 'primary_tag', 'mode': 'PREFIX'};
Defensive patterns

Strategy: validation

Validate before calling

// reject collections/UDTs before SASI index creation
DataType type = tableMetadata.getColumn(targetName).getType();
if (type instanceof CollectionType || type.isUDT())
    throw new IllegalArgumentException("SASI cannot index complex column: " + targetName);

Try / catch

try {
    session.execute(createIndexStmt);
} catch (InvalidQueryException e) {
    if (e.getMessage().contains("complex columns are not yet supported")) { /* choose a scalar column */ }
}

Prevention

When it happens

Trigger: Creating a SASI index whose 'target' option resolves to a collection column (list/set/map), a frozen UDT column, or any complex-typed column in the table schema.

Common situations: Trying to build full-text indexes on map or list columns because a regular secondary index is insufficient; attempting to index UDT fields; assuming SASI supports collections as 2i does partially.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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