{"record":{"id":"675aa7f6f8dd8dcf","repo":"apache/cassandra","slug":"complex-columns-are-not-yet-supported-by-sasi","errorCode":null,"errorMessage":"complex columns are not yet supported by SASI","messagePattern":"complex columns are not yet supported by SASI","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sasi/SASIIndex.java","lineNumber":168,"sourceCode":"\n    /**\n     * Called via reflection at {@link IndexMetadata#validateCustomIndexOptions}\n     */\n    public static Map<String, String> validateOptions(Map<String, String> options, TableMetadata metadata)\n    {\n        if (!(metadata.partitioner instanceof Murmur3Partitioner))\n            throw new ConfigurationException(\"SASI only supports Murmur3Partitioner.\");\n\n        String targetColumn = options.get(\"target\");\n        if (targetColumn == null)\n            throw new ConfigurationException(\"unknown target column\");\n\n        Pair<ColumnMetadata, IndexTarget.Type> target = TargetParser.parse(metadata, targetColumn);\n        if (target == null)\n            throw new ConfigurationException(\"failed to retrieve target column for: \" + targetColumn);\n\n        if (target.left.isComplex())\n            throw new ConfigurationException(\"complex columns are not yet supported by SASI\");\n\n        if (target.left.isPartitionKey())\n            throw new ConfigurationException(\"partition key columns are not yet supported by SASI\");\n\n        IndexMode.validateAnalyzer(options, target.left);\n\n        IndexMode mode = IndexMode.getMode(target.left, options);\n        if (mode.mode == Mode.SPARSE)\n        {\n            if (mode.isLiteral)\n                throw new ConfigurationException(\"SPARSE mode is only supported on non-literal columns.\");\n\n            if (mode.isAnalyzed)\n                throw new ConfigurationException(\"SPARSE mode doesn't support analyzers.\");\n        }\n\n        return Collections.emptyMap();\n    }","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sasi/SASIIndex.java#L150-L186","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Move the indexed value into a dedicated scalar column (e.g. denormalize the map value into a text column) and index that.","Index only scalar (non-collection, non-UDT) columns with SASI.","If collection search is required, use a different mechanism (e.g. a separate lookup table or an external search system)."],"exampleFix":"// before\nCREATE CUSTOM INDEX ON users (tags) USING 'org.apache.cassandra.index.sasi.SASIIndex'; // tags is set<text>\n// after: index a scalar projection instead\nCREATE CUSTOM INDEX ON users (primary_tag) USING 'org.apache.cassandra.index.sasi.SASIIndex'\n  WITH OPTIONS = {'target': 'primary_tag', 'mode': 'PREFIX'};","handlingStrategy":"validation","validationCode":"// reject collections/UDTs before SASI index creation\nDataType type = tableMetadata.getColumn(targetName).getType();\nif (type instanceof CollectionType || type.isUDT())\n    throw new IllegalArgumentException(\"SASI cannot index complex column: \" + targetName);","typeGuard":null,"tryCatchPattern":"try {\n    session.execute(createIndexStmt);\n} catch (InvalidQueryException e) {\n    if (e.getMessage().contains(\"complex columns are not yet supported\")) { /* choose a scalar column */ }\n}","preventionTips":["Document that SASI supports only scalar columns.","In schema-review tooling, flag CREATE CUSTOM INDEX statements whose target is a collection or UDT."],"tags":["sasi","unsupported-type","complex-column","cassandra"],"backgroundTag":"unsupported-operation","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"}