{"record":{"id":"3b5b94e0d487f2cf","repo":"apache/druid","slug":"group-key-should-be-a-single-dimension","errorCode":null,"errorMessage":"Group key should be a single dimension","messagePattern":"Group key should be a single dimension","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/GroupByQueryEngine.java","lineNumber":737,"sourceCode":"        GroupByQueryConfig querySpecificConfig,\n        DruidProcessingConfig processingConfig,\n        Cursor cursor,\n        CursorGranularizer granularizer,\n        ByteBuffer buffer,\n        @Nullable DateTime fudgeTimestamp,\n        GroupByColumnSelectorPlus[] dims,\n        boolean allSingleValueDims,\n        int cardinality\n    )\n    {\n      super(query, querySpecificConfig, processingConfig, cursor, granularizer, buffer, fudgeTimestamp, dims, allSingleValueDims);\n      this.cardinality = cardinality;\n      if (dims.length == 1) {\n        this.dim = dims[0];\n      } else if (dims.length == 0) {\n        this.dim = null;\n      } else {\n        throw new IAE(\"Group key should be a single dimension\");\n      }\n    }\n\n    @Override\n    protected IntGrouper newGrouper()\n    {\n      return new BufferArrayGrouper(\n          Suppliers.ofInstance(buffer),\n          AggregatorAdapters.factorizeBuffered(cursor.getColumnSelectorFactory(), query.getAggregatorSpecs()),\n          cardinality\n      );\n    }\n\n    @Override\n    protected void aggregateSingleValueDims(Grouper<IntKey> grouper)\n    {\n      aggregateSingleValueDimsWithIntGrouper((IntGrouper) grouper);\n    }","sourceCodeStart":719,"sourceCodeEnd":755,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/GroupByQueryEngine.java#L719-L755","documentation":"The array-based groupBy aggregate iterator (GroupByQueryEngine) supports grouping on at most one dimension for its IntGrouper fast path. ArrayAggregateIterator's constructor throws an IAE if dims.length > 1, since multi-dimension keys cannot map to the single-int grouping it implements.","triggerScenarios":"Running a groupBy query in the array-capable engine path where the grouping dimensions list resolves to 2+ dimensions for ArrayAggregateIterator — e.g. a groupBy with multiple dimensions routed to the array iterator instead of the general (buffer/array) grouper path.","commonSituations":"Query engine/context selection forcing the array iterator (groupBy enableArray... context flags) with multi-dim queries; auto-engine heuristics picking array path for single-dim-looking queries that actually expand to multiple dims; virtual columns expanding into multiple output dims.","solutions":["Use multiple dimensions only via the standard buffer/array grouper path (remove context flags forcing the array iterator)","Split the query into multiple single-dimension groupBy queries and merge results","Combine dimensions into one via a virtual column/expression (concat) before grouping","Upgrade Druid — newer versions route multi-dim groupings correctly; check version-specific engine selection bugs"],"exampleFix":"// before\ncolumns: [\"dim1\", \"dim2\"] with engine forced to array iterator\n// after\ncolumns: [\"dim1\"] // or remove engine-forcing context key, or use concat expression as a single key","handlingStrategy":"validation","validationCode":"if (dims.length > 1) {\n  throw new IllegalArgumentException(\"Array iterator path supports only a single group dimension; use the standard grouper\");\n}","typeGuard":"boolean isArrayIteratorCompatible(String[] dims) { return dims == null || dims.length <= 1; }","tryCatchPattern":"try { runArrayQuery(query); } catch (IAE e) { if (e.getMessage().equals(\"Group key should be a single dimension\")) { fallbackToStandardGrouper(query); } }","preventionTips":["Only route single-dimension groupings to the array iterator path","Add engine-selection checks that inspect dim count before choosing the iterator","Prefer the buffer grouper for multi-dimension groupBy queries"],"tags":["druid","groupby","array-iterator","unsupported-operation"],"backgroundTag":"unsupported-operation","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}