{"record":{"id":"875b88b8ac202203","repo":"apache/druid","slug":"joining-against-array-columns-is-not-supported","errorCode":null,"errorMessage":"Joining against ARRAY columns is not supported.","messagePattern":"Joining against ARRAY columns is not supported\\.","errorType":"exception","errorClass":"QueryUnsupportedException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/segment/join/table/IndexedTableJoinMatcher.java","lineNumber":500,"sourceCode":"    public ConditionMatcher makeLongProcessor(BaseLongColumnValueSelector selector)\n    {\n      if (index.keyType().is(ValueType.LONG)) {\n        return makePrimitiveLongMatcher(selector);\n      } else if (includeNull) {\n        return () -> selector.isNull() ? index.find(null) : index.find(selector.getLong());\n      } else {\n        return () -> selector.isNull() ? IntSortedSets.EMPTY_SET : index.find(selector.getLong());\n      }\n    }\n\n    @Override\n    public ConditionMatcher makeArrayProcessor(\n        BaseObjectColumnValueSelector<?> selector,\n        @Nullable ColumnCapabilities columnCapabilities\n    )\n    {\n      return () -> {\n        throw new QueryUnsupportedException(\"Joining against ARRAY columns is not supported.\");\n      };\n    }\n\n    @Override\n    public ConditionMatcher makeComplexProcessor(BaseObjectColumnValueSelector<?> selector)\n    {\n      return new ConditionMatcher()\n      {\n        @Override\n        public int matchSingleRow()\n        {\n          return NO_CONDITION_MATCH;\n        }\n\n        @Override\n        public IntSortedSet match()\n        {\n          return IntSortedSets.EMPTY_SET;","sourceCodeStart":482,"sourceCodeEnd":518,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/segment/join/table/IndexedTableJoinMatcher.java#L482-L518","documentation":"Indexed-table hash joins do not support ARRAY-typed columns on the join side. makeArrayProcessor returns a ConditionMatcher that unconditionally throws QueryUnsupportedException whenever the array selector is consulted during matching.","triggerScenarios":"A join condition referencing an ARRAY-typed column of the outer segment or the broadcast table, causing makeConditionMatcher to dispatch to makeArrayProcessor and later evaluate the matcher.","commonSituations":"Joining on Druid native ARRAY columns (e.g. after ARRAY-typed ingestion or SQL ARRAY functions); queries written assuming arrays are treated like multi-value strings.","solutions":["Rewrite the join to use a scalar column instead of an ARRAY column","Convert the array to a string (ARRAY_TO_STRING) or unnest into rows before joining","Store the data as multi-value strings instead of typed arrays if join support is required"],"exampleFix":"// before\n// JOIN ON t.arr = b.key\n// after\n// JOIN ON ARRAY_TO_STRING(t.arr, ',') = b.key  -- or UNNEST the array first","handlingStrategy":"validation","validationCode":"if (columnCapabilities != null && columnCapabilities.getType().isArray()) {\n  throw new UnsupportedOperationException(\"join on ARRAY column\");\n}","typeGuard":null,"tryCatchPattern":"try { matcher.match(...); } catch (QueryUnsupportedException e) { /* rewrite query without array join */ }","preventionTips":["Do not join on typed ARRAY columns; unnest or stringify first","Check column type signatures in the planner before choosing hash join"],"tags":["java","join","array-column","query-unsupported"],"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"}