apache/druid · error · UnsupportedOperationException

Cannot operate on a dimension with unknown cardinality

Error message

Cannot operate on a dimension with unknown cardinality

What it means

This topN algorithm needs the dimension's dictionary-ordered value positions, so it requires a known, non-negative cardinality. When the DimensionSelector's cardinality is unknown (< 0, e.g. selector without dictionary support), Druid throws UnsupportedOperationException("Cannot operate on a dimension with unknown cardinality").

Source

Thrown at processing/src/main/java/org/apache/druid/query/topn/AggregateTopNMetricFirstAlgorithm.java:139

          resultBuilder,
          dimValSelector,
          queryMetrics
      );
    }
    finally {
      allMetricAlgo.cleanup(allMetricsParam);
    }
  }

  @Override
  public void cleanup(TopNParams params)
  {
  }

  private int[] getDimValSelectorForTopNMetric(TopNParams params, TopNResultBuilder resultBuilder)
  {
    if (params.getCardinality() < 0) {
      throw new UnsupportedOperationException("Cannot operate on a dimension with unknown cardinality");
    }

    int[] dimValSelector = new int[params.getCardinality()];
    Arrays.fill(dimValSelector, SKIP_POSITION_VALUE);

    Iterator<DimValHolder> dimValIter = resultBuilder.getTopNIterator();
    while (dimValIter.hasNext()) {
      int dimValIndex = (Integer) dimValIter.next().getDimValIndex();
      dimValSelector[dimValIndex] = INIT_POSITION_VALUE;
    }

    return dimValSelector;
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

1. Rewrite the query as a GroupBy with an orderBy limit — it doesn't need dictionary cardinality
2. Ensure the dimension column is a string column with dictionary encoding (check segment metadata)
3. Remove expression/lookup wrappers on the dimension or pre-materialize the dimension at ingestion
4. Force a different topN algorithm (e.g. default alphabetical/time-order algorithms) that tolerates unknown cardinality

Example fix

// before
{ "queryType": "topN", "dimension": { "type": "extraction", "dimension": "x", ... } }
// after
{ "queryType": "groupBy", "dimensions": ["x"], "limitSpec": { "type": "default", "limit": 10, "columns": ["metric"] } }

int card = selector.getValueCardinality();
boolean safe = card >= 0; // else fall back to groupBy

static boolean hasKnownCardinality(DimensionSelector s) { return s != null && s.getValueCardinality() >= 0; }

try { return topNRun(query); }
catch (UnsupportedOperationException e) {
  if (e.getMessage().contains("unknown cardinality")) { return groupByRunWithLimit(query); }
  throw e;
}

When it happens

Trigger: Running a topN query (with the aggregate-topN-metric-first algorithm) on a dimension whose selector cannot report cardinality — typically a dimension backed by a non-dictionary-encoded column, an expression selector, or a virtual/inline datasource column.

Common situations: TopN on a high-cardinality/roaring-less column type, querying expression dimensions, using columns lacking dictionary encoding after schema/format changes, TopN on a lookup-wrapped dimension without cardinality support.

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

• Cannot operate on a dimension with unknown cardinality
• CardinalityAggregator does not support getFloat()
• CardinalityAggregator does not support getLong()
• CardinalityAggregator does not support getDouble()
• CardinalityBufferAggregator does not support getFloat()

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