apache/druid · error · UnsupportedOperationException

ORC flattener does not support nested root queries

Error message

ORC flattener does not support nested root queries

What it means

OrcStructFlattenerMaker.makeJsonTreeExtractor() only supports single-node (top-level) paths; multi-node paths would require nested JSON-tree traversal that ORC flattening does not implement, so it throws UnsupportedOperationException for nested root queries.

Source

Thrown at extensions-core/orc-extensions/src/main/java/org/apache/druid/data/input/orc/OrcStructFlattenerMaker.java:110

      return finalizeConversion(val);
    };
  }

  @Nullable
  @Override
  public Function<OrcStruct, Object> makeJsonQueryExtractor(String expr)
  {
    throw new UnsupportedOperationException("ORC flattener does not support JQ");
  }

  @Override
  public Function<OrcStruct, Object> makeJsonTreeExtractor(List<String> nodes)
  {
    if (nodes.size() == 1) {
      return (OrcStruct record) -> getRootField(record, nodes.get(0));
    }

    throw new UnsupportedOperationException("ORC flattener does not support nested root queries");
  }

  @Override
  public JsonProvider getJsonProvider()
  {
    return orcJsonProvider;
  }

  @Override
  public Object finalizeConversionForMap(Object o)
  {
    return finalizeConversion(o);
  }

  private Object finalizeConversion(Object o)
  {
    // recursively convert any complex types
    if (o instanceof OrcStruct || o instanceof OrcMap || o instanceof OrcList) {

View on GitHub (pinned to 9b90983fd2)

Solutions

Flatten only top-level ORC columns, or specify a single root field per flatten expression
Use ORC 'path' expressions limited to first-level fields, or restructure data so nested fields are top-level
Use a format with full nested support (e.g. Avro/JSON) if nested extraction is essential

Example fix

// before
{"name":"nested","expr":"$.outer.inner"}
// after
{"name":"inner","expr":"$.inner"}  // or make inner a top-level column

Defensive patterns

Strategy: validation

Validate before calling

final boolean nested = flattenSpec.getFields().stream().anyMatch(f -> f.getExpr() != null && f.getExpr().split("\\.").length > 1);
if (nested) { throw new IllegalArgumentException("ORC flatten supports only single-node (root) expressions"); }

Try / catch

try { extractor = flattenerMaker.makeJsonTreeExtractor(nodes); } catch (UnsupportedOperationException e) { extractor = flattenTopLevelOnly(nodes.get(0)); }

Prevention

Restrict ORC flattenSpec expressions to top-level columns
Promote needed nested fields to top-level during data production
Test flatten specs on a sample ORC file before production ingestion

When it happens

Trigger: Defining an ORC flattenSpec expression whose parsed node list has more than one node (e.g. a nested path like 'a.b' rather than a single root field).

Common situations: Attempting to flatten nested ORC struct fields with dot-separated expressions; migrating flatten configs from formats that support nested extraction (JSON) to ORC.

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/1cb47640af2ef85f. Report an issue: GitHub.