apache/druid · error · UnsupportedOperationException

Vectorized matcher cannot make string matcher for ARRAY type

Error message

Vectorized matcher cannot make string matcher for ARRAY types

What it means

ArrayVectorValueMatcher backs vectorized matching for ARRAY-typed columns. String equality matching is not supported for array columns because a vector of arrays cannot be compared to a single string, so makeMatcher(String) always throws UnsupportedOperationException.

Source

Thrown at processing/src/main/java/org/apache/druid/query/filter/vector/ArrayVectorValueMatcher.java:48

public class ArrayVectorValueMatcher implements VectorValueMatcherFactory
{
  protected final TypeSignature<ValueType> columnType;
  protected final VectorObjectSelector selector;

  public ArrayVectorValueMatcher(
      TypeSignature<ValueType> columnType,
      VectorObjectSelector selector
  )
  {
    this.columnType = columnType;
    this.selector = selector;
  }

  @Override
  public VectorValueMatcher makeMatcher(@Nullable String value)
  {
    throw new UnsupportedOperationException(
        "Vectorized matcher cannot make string matcher for ARRAY types"
    );
  }

  @Override
  public VectorValueMatcher makeMatcher(Object matchValue, ColumnType matchValueType)
  {
    throw new UnsupportedOperationException(
        "Vectorized matcher cannot make object matcher for ARRAY types"
    );
  }

  @Override
  public VectorValueMatcher makeMatcher(DruidPredicateFactory predicateFactory)
  {
    final DruidObjectPredicate<Object[]> predicate = predicateFactory.makeArrayPredicate(columnType);
    return new BaseVectorValueMatcher(selector)
    {

View on GitHub (pinned to 9b90983fd2)

Solutions

Filter array columns with array-typed values or predicate-factory matchers (makeMatcher(DruidPredicateFactory)) instead of a string value.
Disable vectorization for the query (vectorize=false in query context) so the row-based path handles the array filter.
Use UNNEST or ARRAY_CONTAINS-style semantics (e.g. filter on the unnested output column) rather than direct array equality.

Example fix

// before
new SelectorDimFilter("arrayCol", "value", null); // vectorized on ARRAY
// after
// run with query context {"vectorize":"false"} or use a predicate-based filter
new InDimFilter("arrayCol", Collections.singletonList("value"), null); // non-vector path, or unnest first

Defensive patterns

Strategy: validation

Validate before calling

if (columnType.isArray()) { /* avoid string-value matcher; use predicate factory or disable vectorization */ }

Type guard

boolean supportsStringMatcher = !ColumnType.ofArrayOrNot(colType).isArray();

Try / catch

try { matcher = arrayMatcher.makeMatcher(value); } catch (UnsupportedOperationException e) { /* disable vectorization or use predicate matcher */ }

Prevention

Check column type is not ARRAY before applying string-value vector filters
Use DruidPredicateFactory matchers for array columns
Set vectorize=false for queries filtering ARRAY columns by value

When it happens

Trigger: A vectorized filter on an ARRAY column attempts a string-value matcher (e.g. a selector filter with a string value applied to an array-typed column via the vector engine).

Common situations: Queries filtering array columns with equality to a string while vectorization is enabled; queries written for multi-value string columns now stored as ARRAY types.

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

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