{"record":{"id":"3a32e1783ef320fc","repo":"apache/cassandra","slug":"sparse-mode-is-only-supported-on-non-literal-colum","errorCode":null,"errorMessage":"SPARSE mode is only supported on non-literal columns.","messagePattern":"SPARSE mode is only supported on non-literal columns\\.","errorType":"validation","errorClass":"ConfigurationException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/index/sasi/SASIIndex.java","lineNumber":179,"sourceCode":"            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    }\n\n    @Override\n    public void register(IndexRegistry registry)\n    {\n        registry.registerIndex(this, new Group.Key(this), () -> new SASIIndexGroup(this));\n    }\n\n    public IndexMetadata getIndexMetadata()\n    {\n        return config;\n    }","sourceCodeStart":161,"sourceCodeEnd":197,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/index/sasi/SASIIndex.java#L161-L197","documentation":"The SPARSE SASI mode is an optimization for low-cardinality, non-literal (numeric/timestamp) columns. When IndexMode.getMode returns Mode.SPARSE but the resolved mode is for a literal (text-like) column, validateOptions throws this ConfigurationException because SPARSE token layout is meaningless for strings.","triggerScenarios":"Declaring 'mode': 'SPARSE' in SASI index options on a text/ascii/varchar (literal-typed) target column.","commonSituations":"Copying SPARSE configuration from a numeric-column example onto a text column; bulk-configuring indexes with a single mode string regardless of column type.","solutions":["Change mode to PREFIX, CONTAINS, or SUFFIX (omit to use the default) for the literal column.","If SPARSE is intended, confirm the target column is a non-literal type (int, bigint, timestamp, etc.).","Remove the 'mode' option entirely to let SASI pick the appropriate default."],"exampleFix":"// before (column 'email' is text)\nWITH OPTIONS = {'target': 'email', 'mode': 'SPARSE'};\n// after\nWITH OPTIONS = {'target': 'email', 'mode': 'CONTAINS', 'analyzed': 'true', 'analyzer_class': 'org.apache.cassandra.index.sasi.analyzer.StandardAnalyzer'};","handlingStrategy":"validation","validationCode":"// only allow SPARSE on non-literal types\nif (\"SPARSE\".equals(options.get(\"mode\")) && isLiteralType(columnType))\n    throw new IllegalArgumentException(\"SPARSE mode requires a non-literal column\");","typeGuard":null,"tryCatchPattern":"try {\n    session.execute(createIndexStmt);\n} catch (InvalidQueryException e) {\n    if (e.getMessage().contains(\"SPARSE mode is only supported\")) { /* drop or change the mode option */ }\n}","preventionTips":["Map column types to allowed modes in config tooling (SPARSE only for numeric/date columns).","Prefer the default mode unless SPARSE is a measured win."],"tags":["sasi","invalid-config-value","mode-mismatch","cassandra"],"backgroundTag":"invalid-config-value","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"}