{"record":{"id":"c8b8a353496d0a53","repo":"apache/cassandra","slug":"clustering-column-restrictions-require-the-use-of","errorCode":null,"errorMessage":"Clustering column restrictions require the use of secondary indices or filtering for map-element restrictions and for the following operators: %s","messagePattern":"Clustering column restrictions require the use of secondary indices or filtering for map-element restrictions and for the following operators: (.+?)","errorType":"validation","errorClass":"InvalidRequestException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/cql3/restrictions/StatementRestrictions.java","lineNumber":680,"sourceCode":"    private void processClusteringColumnsRestrictions(boolean hasQueriableIndex,\n                                                      boolean selectsOnlyStaticColumns,\n                                                      boolean forView,\n                                                      boolean allowFiltering)\n    {\n        checkFalse(!type.allowClusteringColumnSlices() && clusteringColumnsRestrictions.hasSlice(),\n                   \"Slice restrictions are not supported on the clustering columns in %s statements\", type);\n\n        if (!type.allowClusteringColumnSlices()\n            && (!table.isCompactTable() || (table.isCompactTable() && !hasClusteringColumnsRestrictions())))\n        {\n            if (!selectsOnlyStaticColumns && hasUnrestrictedClusteringColumns())\n                throw invalidRequest(\"Some clustering keys are missing: %s\",\n                                     Joiner.on(\", \").join(getUnrestrictedClusteringColumns()));\n        }\n        else\n        {\n            if (clusteringColumnsRestrictions.needsFilteringOrIndexing() && !hasQueriableIndex && !allowFiltering)\n                throw invalidRequest(\"Clustering column restrictions require the use of secondary indices\" +\n                                     \" or filtering for map-element restrictions and for the following operators: %s\",\n                                     Operator.operatorsRequiringFilteringOrIndexingFor(ColumnMetadata.Kind.CLUSTERING)\n                                             .stream()\n                                             .map(Operator::toString)\n                                             .collect(Collectors.joining(\", \")));\n\n            if (hasClusteringColumnsRestrictions() && clusteringColumnsRestrictions.needFiltering())\n            {\n                if (hasQueriableIndex || forView)\n                {\n                    usesSecondaryIndexing = true;\n                }\n                else if (!allowFiltering)\n                {\n                    List<ColumnMetadata> clusteringColumns = table.clusteringColumns();\n                    List<ColumnMetadata> restrictedColumns = new ArrayList<>(clusteringColumnsRestrictions.columns());\n\n                    for (int i = 0, m = restrictedColumns.size(); i < m; i++)","sourceCodeStart":662,"sourceCodeEnd":698,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/cql3/restrictions/StatementRestrictions.java#L662-L698","documentation":"Certain clustering column restrictions (map-element access like c['k'] = v, and operators such as CONTAINS, !=, LIKE, NEQ, NOT IN) cannot be satisfied by normal key matching; they require a secondary index or ALLOW FILTERING. When none is present, StatementRestrictions throws this error listing the offending operators.","triggerScenarios":"SELECT * FROM t WHERE pk = 'a' AND clustering_map['key'] = 'v' with no index and no ALLOW FILTERING; clustering column with CONTAINS / != / NOT IN relations without an index.","commonSituations":"Filtering on map entries inside clustering columns; using inequality or negation operators on clustering keys inherited from SQL habits; queries that worked because an index was later dropped.","solutions":["Append ALLOW FILTERING if the restricted partition is small and performance is acceptable","Create a secondary/custom index on the clustering column (e.g. index on keys(entry_map) or values(entry_map))","Rewrite the query to use only EQ/IN/slice operators on clustering columns","Restructure the schema (e.g. promote the map key into the clustering key) for direct lookup"],"exampleFix":"// before\nSELECT * FROM t WHERE pk = 'a' AND attrs['env'] = 'prod';\n// after\nCREATE INDEX t_attrs_keys ON t (KEYS(attrs));\nSELECT * FROM t WHERE pk = 'a' AND attrs['env'] = 'prod';","handlingStrategy":"validation","validationCode":"// Only allow EQ/IN/slice operators on clustering columns without an index;\n// flag map-element access (c['k']) and CONTAINS/!=/NOT IN as requiring index or ALLOW FILTERING.","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Restrict clustering columns to equality/IN/range predicates","Create indexes for any map-element or CONTAINS filtering you need","Model frequently filtered map keys as real columns"],"tags":["cql","cassandra","filtering","indexing"],"backgroundTag":"feature-not-enabled","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}