apache/beam · error · UnsupportedOperationException

Creating tables is not supported in HCatalog

Error message

Creating tables is not supported in HCatalog

What it means

The HCatalog DatabaseProvider is read-only: schema/tables in a Hive metastore are managed by Hive itself, not Beam SQL. Any attempt to create a table through this provider throws UnsupportedOperationException.

Solutions

  1. Create the table in Hive/HCatalog first (Hive DDL), then query it from Beam SQL.
  2. Use a different table provider that supports DDL (e.g. in-memory, iceberg if applicable).
  3. Remove CREATE TABLE statements from the Beam SQL query and treat metastore tables as pre-existing.

Example fix

// before
CREATE TABLE hcatalog.db.tbl (id INT) AS SELECT 1;
// after
// run DDL in Hive first, then in Beam SQL:
SELECT * FROM hcatalog.db.tbl;
Defensive patterns

Strategy: validation

Validate before calling

if ("hcatalog".equals(provider.getTableType()) && needsDdl) {
  throw new IllegalArgumentException("Issue Hive DDL externally; hcatalog provider is read-only");
}

Try / catch

try {
  provider.createTable(table);
} catch (UnsupportedOperationException e) {
  // fall back to Hive metastore client DDL
}

Prevention

When it happens

Trigger: Invoking createTable(Table) on the hcatalog table provider (e.g. via a 'CREATE TABLE' statement or TableProvider.createTable API).

Common situations: Running DDL like CREATE TABLE against an hcatalog catalog in Beam SQL; porting pipelines written for other providers (e.g. in-memory, text) to HCatalog.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/fb013422f20d985f. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/extensions/sql/hcatalog/src/main/java/org/apache/beam/sdk/extensions/sql/meta/provider/hcatalog/DatabaseProvider.java:57

  DatabaseProvider(String db, HCatalogBeamSchema metastoreSchema, Map<String, String> config) {
    this.db = db;
    this.metastoreSchema = metastoreSchema;
    this.config = config;
  }

  String getDb() {
    return db;
  }

  @Override
  public String getTableType() {
    return "hcatalog";
  }

  @Override
  public void createTable(Table table) {
    throw new UnsupportedOperationException("Creating tables is not supported in HCatalog");
  }

  @Override
  public void dropTable(String tableName) {
    throw new UnsupportedOperationException("Deleting tables is not supported in HCatalog");
  }

  @Override
  public Map<String, Table> getTables() {
    throw new UnsupportedOperationException("Listing tables is not supported in HCatalog");
  }

  /** Table metadata to pass the schema to Calcite. */
  @Override
  public @Nullable Table getTable(String table) {
    Optional<Schema> tableSchema = metastoreSchema.getTableSchema(db, table);
    if (!tableSchema.isPresent()) {
      return null;

View on GitHub (pinned to 12126d8942)