{"record":{"id":"7e0dcbfa02cf3c8c","repo":"apache/druid","slug":"cannot-operate-on-a-dimension-with-unknown-cardina","errorCode":null,"errorMessage":"Cannot operate on a dimension with unknown cardinality","messagePattern":"Cannot operate on a dimension with unknown cardinality","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"processing/src/main/java/org/apache/druid/query/topn/AggregateTopNMetricFirstAlgorithm.java","lineNumber":139,"sourceCode":"          resultBuilder,\n          dimValSelector,\n          queryMetrics\n      );\n    }\n    finally {\n      allMetricAlgo.cleanup(allMetricsParam);\n    }\n  }\n\n  @Override\n  public void cleanup(TopNParams params)\n  {\n  }\n\n  private int[] getDimValSelectorForTopNMetric(TopNParams params, TopNResultBuilder resultBuilder)\n  {\n    if (params.getCardinality() < 0) {\n      throw new UnsupportedOperationException(\"Cannot operate on a dimension with unknown cardinality\");\n    }\n\n    int[] dimValSelector = new int[params.getCardinality()];\n    Arrays.fill(dimValSelector, SKIP_POSITION_VALUE);\n\n    Iterator<DimValHolder> dimValIter = resultBuilder.getTopNIterator();\n    while (dimValIter.hasNext()) {\n      int dimValIndex = (Integer) dimValIter.next().getDimValIndex();\n      dimValSelector[dimValIndex] = INIT_POSITION_VALUE;\n    }\n\n    return dimValSelector;\n  }\n}\n","sourceCodeStart":121,"sourceCodeEnd":154,"githubUrl":"https://github.com/apache/druid/blob/9b90983fd291f26935af934383ce360473179e4d/processing/src/main/java/org/apache/druid/query/topn/AggregateTopNMetricFirstAlgorithm.java#L121-L154","documentation":"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\").","triggerScenarios":"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.","commonSituations":"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.","solutions":["Rewrite the query as a GroupBy with an orderBy limit — it doesn't need dictionary cardinality","Ensure the dimension column is a string column with dictionary encoding (check segment metadata)","Remove expression/lookup wrappers on the dimension or pre-materialize the dimension at ingestion","Force a different topN algorithm (e.g. default alphabetical/time-order algorithms) that tolerates unknown cardinality"],"exampleFix":"// before\n{ \"queryType\": \"topN\", \"dimension\": { \"type\": \"extraction\", \"dimension\": \"x\", ... } }\n// after\n{ \"queryType\": \"groupBy\", \"dimensions\": [\"x\"], \"limitSpec\": { \"type\": \"default\", \"limit\": 10, \"columns\": [\"metric\"] } }","handlingStrategy":"fallback","validationCode":"int card = selector.getValueCardinality();\nboolean safe = card >= 0; // else fall back to groupBy","typeGuard":"static boolean hasKnownCardinality(DimensionSelector s) { return s != null && s.getValueCardinality() >= 0; }","tryCatchPattern":"try { return topNRun(query); }\ncatch (UnsupportedOperationException e) {\n  if (e.getMessage().contains(\"unknown cardinality\")) { return groupByRunWithLimit(query); }\n  throw e;\n}","preventionTips":["Prefer groupBy+limit for expression/lookup dimensions","Ensure dimensions are dictionary-encoded string columns","Avoid topN on virtual columns"],"tags":["druid","topn","cardinality","unsupported-dimension"],"backgroundTag":"unsupported-operation","analyzedSha":"9b90983fd291f26935af934383ce360473179e4d","analyzedAt":"2026-09-07T13:32:30.957Z","contentChangedAt":"2026-09-07T13:32:30.957Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}