apache/druid · error · java.lang.IllegalArgumentException

requires a ThetaSketch as the argument

Error message

requires a ThetaSketch as the argument

What it means

The THETA_SKETCH_ESTIMATE expression macro evaluates its argument expecting a SketchHolder (a theta sketch aggregation result). If the evaluated value is any other object, it throws an IllegalArgumentException because an estimate can only be computed from a theta sketch.

Source

Thrown at extensions-core/datasketches/src/main/java/org/apache/druid/query/aggregation/datasketches/theta/sql/ThetaPostAggMacros.java:95

    {
      super(macro, args);
      this.estimateExpr = Iterables.getOnlyElement(args);
    }

    @Override
    public ExprEval eval(ObjectBinding bindings)
    {
      ExprEval eval = estimateExpr.eval(bindings);
      final Object valObj = eval.value();
      if (valObj == null) {
        return ExprEval.ofDouble(null);
      }
      if (valObj instanceof SketchHolder) {
        SketchHolder thetaSketchHolder = (SketchHolder) valObj;
        double estimate = thetaSketchHolder.getEstimate();
        return ExprEval.of(estimate);
      } else {
        throw new IllegalArgumentException("requires a ThetaSketch as the argument");
      }
    }

    @Nullable
    @Override
    public ExpressionType getOutputType(InputBindingInspector inspector)
    {
      return ExpressionType.DOUBLE;
    }
  }

  public static class ThetaSketchEstimateWithErrorBoundsExpr extends ExprMacroTable.BaseScalarMacroFunctionExpr
  {
    private Expr estimateExpr;
    private Expr numStdDev;

    public ThetaSketchEstimateWithErrorBoundsExpr(ThetaSketchEstimateWithErrorBoundsExprMacro macro, List<Expr> args)
    {

View on GitHub (pinned to 9b90983fd2)

Solutions

  1. Ensure the argument column is produced by a thetaSketch aggregator (a SketchHolder complex column) in the same query
  2. Register/keep the datasketches extension loaded on all nodes so the complex column deserializes as a SketchHolder
  3. Check the SQL query: use THETA_SKETCH_ESTIMATE with the aggregator's output, not a raw column
  4. If reading stored sketches from a string column, convert them into a proper sketch complex column first

Example fix

// before
SELECT THETA_SKETCH_ESTIMATE(user_id) FROM events -- user_id is a long
// after
SELECT THETA_SKETCH_ESTIMATE(theta_sketch) FROM (
  SELECT APX_SKETCH_ESTIMATE(...)... -- or
)
SELECT APPROX_COUNT_DISTINCT_DS_THETA(user_id) FROM events -- correct: aggregator output is a SketchHolder
Defensive patterns

Strategy: type-guard

Validate before calling

// in expression/SQL context, ensure the argument is the output of a theta sketch aggregator
if (!(valObj instanceof SketchHolder)) {
  throw new IllegalArgumentException("theta_estimate argument must be a theta sketch column");
}

Type guard

boolean isThetaSketch(Object o) {
  return o instanceof SketchHolder;
}

Try / catch

try {
  ExprEval v = macro.eval(bindings);
} catch (IllegalArgumentException e) {
  // argument was not a SketchHolder; check the query uses the theta sketch aggregator output
}

Prevention

When it happens

Trigger: Calling theta_estimate(expr) in a Druid SQL/expression context where expr resolves to a number, string, or non-theta complex type instead of a SketchHolder produced by a theta sketch aggregator.

Common situations: Applying theta_estimate to a plain numeric column or to a stringly-typed sketch column (e.g. base64 stored in a string column rather than a complex sketch column); using theta_estimate outside a query that includes the theta sketch aggregator in the same stage; version skew where the column's complex type registry lacks the theta serializer.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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