apache/druid · error · QueryUnsupportedException

Joining against ARRAY columns is not supported.

Error message

Joining against ARRAY columns is not supported.

What it means

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.

Solutions

1. Rewrite the join to use a scalar column instead of an ARRAY column
2. Convert the array to a string (ARRAY_TO_STRING) or unnest into rows before joining
3. Store the data as multi-value strings instead of typed arrays if join support is required

Example fix

// before
// JOIN ON t.arr = b.key
// after
// JOIN ON ARRAY_TO_STRING(t.arr, ',') = b.key  -- or UNNEST the array first

if (columnCapabilities != null && columnCapabilities.getType().isArray()) {
  throw new UnsupportedOperationException("join on ARRAY column");
}

try { matcher.match(...); } catch (QueryUnsupportedException e) { /* rewrite query without array join */ }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• Joining against a multi-value dimension is not supported.
• Caching is not supported. Check `isCacheable` before…
• Cannot build hash-join matcher on non-equi-join condition
• Cannot build hash-join matcher on non-key-based condition
• Cannot join lookup with condition referring to non-key…

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/875b88b8ac202203. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/join/table/IndexedTableJoinMatcher.java:500

    public ConditionMatcher makeLongProcessor(BaseLongColumnValueSelector selector)
    {
      if (index.keyType().is(ValueType.LONG)) {
        return makePrimitiveLongMatcher(selector);
      } else if (includeNull) {
        return () -> selector.isNull() ? index.find(null) : index.find(selector.getLong());
      } else {
        return () -> selector.isNull() ? IntSortedSets.EMPTY_SET : index.find(selector.getLong());
      }
    }

    @Override
    public ConditionMatcher makeArrayProcessor(
        BaseObjectColumnValueSelector<?> selector,
        @Nullable ColumnCapabilities columnCapabilities
    )
    {
      return () -> {
        throw new QueryUnsupportedException("Joining against ARRAY columns is not supported.");
      };
    }

    @Override
    public ConditionMatcher makeComplexProcessor(BaseObjectColumnValueSelector<?> selector)
    {
      return new ConditionMatcher()
      {
        @Override
        public int matchSingleRow()
        {
          return NO_CONDITION_MATCH;
        }

        @Override
        public IntSortedSet match()
        {
          return IntSortedSets.EMPTY_SET;

View on GitHub (pinned to 9b90983fd2)