What causes "Function requires a schema: TABLE(%s(...)) ( ...)" in apache/druid?

Append the schema: TABLE(fn(args) (colName TYPE, ...)).

apache/druid · error · IllegalArgumentException

Function requires a schema: TABLE(%s(...)) (<col> <type>...)

Error message

Function requires a schema: TABLE(%s(...)) (<col> <type>...)

What it means

BaseTableFunction.requireSchema throws this when a table function is invoked without a column schema. Druid's TABLE(...) functions need an explicit column list (<col> <type>...) because the underlying data source provides none.

Source

Thrown at server/src/main/java/org/apache/druid/catalog/model/table/BaseTableFunction.java:91

  }

  private final List<ParameterDefn> parameters;

  public BaseTableFunction(List<ParameterDefn> parameters)
  {
    this.parameters = parameters;
  }

  @Override
  public List<ParameterDefn> parameters()
  {
    return parameters;
  }

  protected static void requireSchema(String fnName, List<ColumnSpec> columns)
  {
    if (columns == null) {
      throw new IAE(
          "Function requires a schema: TABLE(%s(...)) (<col> <type>...)",
          fnName
      );
    }
  }
}

View on GitHub (pinned to 9b90983fd2)

Solutions

Append the schema: TABLE(fn(args) (colName TYPE, ...)).
Infer the schema first, then re-issue the query with explicit columns.
Check the function's javadoc for which functions require a schema.
For inline/local data, provide columns matching the parsed format fields.

Example fix

// before
SELECT * FROM TABLE(extern("data"))
// after
SELECT * FROM TABLE(extern("data") (col1 VARCHAR, col2 BIGINT))

Defensive patterns

Strategy: validation

Validate before calling

// verify the TABLE(...) SQL includes a schema clause before execution
if (!sql.matches(".*TABLE\\s*\\([^)]*\\)\\s*\\(.*\\).*")) {
  throw new IllegalArgumentException("TABLE function requires (col TYPE, ...) schema");
}

Try / catch

try { runQuery(sql); } catch (IAE e) { if (e.getMessage().contains("requires a schema")) { sql = addSchemaClause(sql, inferredColumns); runQuery(sql); } }

Prevention

Always append (col TYPE, ...) to TABLE() function calls
Infer schema via sampling first, then write explicit schema
Use IDE/console SQL editors that surface table function signatures
Document required schemas for custom table functions

When it happens

Trigger: Calling a table function like TABLE(extern(...)(...)) omitting the parenthesized schema entirely (columns == null passed to requireSchema).

Common situations: Writing SQL like SELECT * FROM TABLE(extern('...')) without the '(col1 col2 ...)' schema suffix; generating table function SQL programmatically and dropping the schema clause.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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