apache/beam · error · ParseException

'CREATE TABLE' is not supported in SQL. You can use 'CREATE…

Error message

'CREATE TABLE' is not supported in SQL. You can use 'CREATE EXTERNAL TABLE' to register an external data source to SQL. For more details, please check: https://beam.apache.org/documentation/dsls/sql/create-external-table

What it means

A deliberate parse error: Beam SQL's grammar has no CREATE TABLE support. When the parser sees CREATE TABLE it immediately throws this ParseException pointing users to CREATE EXTERNAL TABLE, which is Beam SQL's mechanism to register an external data source.

Solutions

Rewrite the statement as CREATE EXTERNAL TABLE ... (type, location) to register the data source.
For in-memory data, construct a PCollection with a schema and apply SqlTransform.query instead of DDL.
Consult https://beam.apache.org/documentation/dsls/sql/create-external-table for the supported syntax.

Example fix

// before
CREATE TABLE orders (id INT, amount DOUBLE);
// after
CREATE EXTERNAL TABLE orders (id INT, amount DOUBLE)
TYPE 'csv'
LOCATION '/path/to/orders/';

Defensive patterns

Strategy: validation

Validate before calling

// reject unsupported DDL before handing to Beam SQL
static void rejectCreateTable(String sql) {
  if (sql.trim().toUpperCase().matches("^CREATE\\s+(OR\\s+REPLACE\\s+)?TABLE\\b.*")) {
    throw new IllegalArgumentException("Use CREATE EXTERNAL TABLE instead of CREATE TABLE in Beam SQL.");
  }
}

Try / catch

try {
  result = pipeline.apply(SqlTransform.query(sql));
} catch (ParseException e) {
  if (e.getMessage() != null && e.getMessage().contains("'CREATE TABLE' is not supported")) {
    throw new IllegalArgumentException("Rewrite as CREATE EXTERNAL TABLE ... TYPE ... LOCATION ...", e);
  }
  throw e;
}

Prevention

Always use CREATE EXTERNAL TABLE with TYPE and LOCATION for data source registration.
Add a SQL lint step that rejects standard CREATE TABLE DDL in Beam pipelines.
When porting from other SQL engines, review all DDL statements for Beam SQL support.

When it happens

Trigger: Running any statement of the form CREATE TABLE [IF NOT EXISTS] name (...) (or CREATE OR REPLACE TABLE) through BeamSql / SqlTransform; also triggered by CREATE REPLACE TABLE via the replace flag routing into this production.

Common situations: Porting DDL from Hive/Spark SQL/MySQL into Beam SQL pipelines; generating schema-based pipelines where authors assume standard CREATE TABLE; old tutorials/scripts.

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/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/f047209bdeb8a2d1. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/extensions/sql/src/main/codegen/includes/parserImpls.ftl:693

        jarName = StringLiteral()
    {
        return
            new SqlCreateFunction(
                s.end(this),
                replace,
                name,
                jarName,
                isAggregate);
    }
}

SqlCreate SqlCreateTableNotSupportedMessage(Span s, boolean replace) :
{
}
{
  <TABLE>
  {
    throw new ParseException("'CREATE TABLE' is not supported in SQL. You can use "
    + "'CREATE EXTERNAL TABLE' to register an external data source to SQL. For more details, "
    + "please check: https://beam.apache.org/documentation/dsls/sql/create-external-table");
  }
}

SqlDrop SqlDropTable(Span s, boolean replace) :
{
    final boolean ifExists;
    final SqlIdentifier id;
}
{
    <TABLE> ifExists = IfExistsOpt() id = CompoundIdentifier() {
        return SqlDdlNodes.dropTable(s.end(this), ifExists, id);
    }
}

/**
 * SHOW TABLES [ ( FROM | IN )? [ catalog_name '.' ] database_name ] [ LIKE regex_pattern ]

View on GitHub (pinned to 12126d8942)