apache/druid · warning · UnsupportedOperationException

Vectorized groupBys on multi-value dictionary-encoded dimens

Error message

Vectorized groupBys on multi-value dictionary-encoded dimensions are not yet implemented

What it means

GroupByVectorColumnProcessorFactory.makeMultiValueDimensionProcessor always throws UnsupportedOperationException: the vectorized group-by engine has no selector implementation for multi-value (array-valued) dictionary-encoded STRING dimensions. Queries hitting this path must fall back to the non-vectorized engine.

Source

Thrown at processing/src/main/java/org/apache/druid/query/groupby/epinephelinae/vector/GroupByVectorColumnProcessorFactory.java:68

  {
    Preconditions.checkArgument(
        capabilities.is(ValueType.STRING),
        "groupBy dimension processors must be STRING typed"
    );
    return new SingleValueStringGroupByVectorColumnSelector(selector);
  }

  @Override
  public GroupByVectorColumnSelector makeMultiValueDimensionProcessor(
      final ColumnCapabilities capabilities,
      final MultiValueDimensionVectorSelector selector
  )
  {
    Preconditions.checkArgument(
        capabilities.is(ValueType.STRING),
        "groupBy dimension processors must be STRING typed"
    );
    throw new UnsupportedOperationException(
        "Vectorized groupBys on multi-value dictionary-encoded dimensions are not yet implemented"
    );
  }

  @Override
  public GroupByVectorColumnSelector makeFloatProcessor(
      final ColumnCapabilities capabilities,
      final VectorValueSelector selector
  )
  {
    if (capabilities.hasNulls().isFalse()) {
      return new FloatGroupByVectorColumnSelector(selector);
    }
    return new NullableFloatGroupByVectorColumnSelector(selector);
  }

  @Override
  public GroupByVectorColumnSelector makeDoubleProcessor(

View on GitHub (pinned to 9b90983fd2)

Solutions

Disable vectorization for this query (set query context "vectorize":"false") or for the datasource so the non-vector engine handles it.
Flatten the multi-value dimension at ingestion (e.g. use a transform to join values into a single string, or explode rows).
Use an expression virtual column that picks a single value (e.g. array_element/array_ordinal) so the dimension becomes single-valued.

Example fix

// before: dimension "tags" is multi-valued, query runs vectorized
// after: context
{"vectorize":"false"}
// or at ingestion, transform: {"type":"expression","expression":"array_to_string(tags,',')","name":"tagsFlat"} and group by tagsFlat

Defensive patterns

Strategy: type-guard

Validate before calling

ColumnCapabilities caps = pool.getColumnCapabilities(column);
boolean mvSupported = caps == null || caps.getType() != ValueType.STRING || !caps.hasMultipleValues().isTrue();

Type guard

boolean isSingleValueString(ColumnCapabilities caps) {
  return caps != null && caps.is(ValueType.STRING) && caps.hasMultipleValues().isNotTrue();
}

Try / catch

try {
  runVectorized(query);
} catch (UnsupportedOperationException e) {
  return runNonVectorized(query); // context vectorize=false
}

Prevention

Set "vectorize":"false" in query context for queries grouping on multi-value dimensions
Flatten multi-value dimensions at ingestion time
Check ColumnCapabilities.hasMultipleValues before relying on vectorized groupBy

When it happens

Trigger: A vectorized groupBy query whose grouping dimension is a multi-value (repeated) string column, with vectorization enabled and the column capabilities reporting hasMultipleValues=true and type STRING.

Common situations: Grouping on a nested/JSON-extracted field or an ingestion dimension that sometimes contains arrays; users upgrading who expect MV support in the vectorized engine; auto-vectorization silently attempting an MV dimension.

Related errors

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