apache/druid · error · QueryUnsupportedException

Joining against a multi-value dimension is not supported.

Error message

Joining against a multi-value dimension is not supported.

What it means

The join system cannot handle multi-valued (array-like) dimension rows on the outer side of an indexed-table join. When a dimension selector returns a row with more than one value during matching, makeDimensionProcessor's matcher throws QueryUnsupportedException instead of producing wrong results.

Solutions

1. Unnest the multi-valued column before joining (SQL UNNEST or flattened ingestion)
2. Disable multi-value handling by using UNNEST or transforming with ARRAY_TO_STRING if a single value suffices
3. Filter or group so the join key column is single-valued per row
4. Track/await upstream fix for the multi-value join limitation (druid issue 9924)

Example fix

// before
// SELECT ... FROM mvTable JOIN broadcast ON mvTable.tags = dim.tags
// after
// SELECT ... FROM (SELECT id, tag FROM mvTable, UNNEST(tags) AS tag) mvTable
//   JOIN broadcast ON mvTable.tag = dim.tags

ColumnCapabilities caps = column.getCapabilities();
boolean multiValue = caps != null && caps.hasMultipleValues().isTrue();

try { matcher.match(forceMultiValue); } catch (QueryUnsupportedException e) { /* rewrite query with UNNEST or fail gracefully */ }

When it happens

Trigger: A join query where the outer/left side column matched in the equality is a multi-value dimension (a row containing multiple values), evaluated via makeConditionMatcher -> makeDimensionProcessor.

Common situations: Joining a table against an ingestion-time multi-valued string dimension (list of tags, array-like input without schema); Kafka/batch ingestion producing MV dimensions; queries mixing MV dimensions with broadcast joins.

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 ARRAY columns 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/03dce13d95b7e40f. Report an issue: GitHub.

Appendix: source

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

      // set outside of the supplier. Minimizing overhead is desirable since the supplier is called from a hot loop for
      // joins.

      if (selector.getValueCardinality() == DimensionDictionarySelector.CARDINALITY_UNKNOWN) {
        // If the cardinality is unknown, then the selector does not have a "real" dictionary and the dimension id
        // is not valid outside the context of a specific row. This means we cannot use a cache and must fall
        // back to this slow code path.
        return () -> {
          final IndexedInts row = selector.getRow();

          if (row.size() == 1) {
            int dimensionId = row.get(0);
            return getRowNumbers(selector.lookupName(dimensionId));
          } else if (row.size() == 0) {
            return getRowNumbers(null);
          } else {
            // Multi-valued rows are not handled by the join system right now
            // TODO: Remove when https://github.com/apache/druid/issues/9924 is done
            throw new QueryUnsupportedException("Joining against a multi-value dimension is not supported.");
          }
        };
      } else {
        // If the cardinality is known, then the dimension id is still valid outside the context of a specific row and
        // its mapping to row numbers can be cached.
        return () -> {
          final IndexedInts row = selector.getRow();

          if (row.size() == 1) {
            int dimensionId = row.get(0);
            return getAndCacheRowNumbers(selector, dimensionId);
          } else if (row.size() == 0) {
            return getRowNumbers(null);
          } else {
            // Multi-valued rows are not handled by the join system right now
            // TODO: Remove when https://github.com/apache/druid/issues/9924 is done
            throw new QueryUnsupportedException("Joining against a multi-value dimension is not supported.");
          }

View on GitHub (pinned to 9b90983fd2)