apache/iceberg · error · IcebergAnalysisException

ALTER VIEW <viewName> AS is not supported. Use CREATE OR REP

Error message

ALTER VIEW <viewName> AS is not supported. Use CREATE OR REPLACE VIEW instead

What it means

Iceberg's view support (CheckViews extension) does not implement ALTER VIEW ... AS ... for session-catalog v2 views. Since Iceberg views are replaced via CREATE OR REPLACE VIEW, ALTER VIEW AS is explicitly rejected with this IcebergAnalysisException.

Source

Thrown at spark/v4.1/spark-extensions/src/main/scala/org/apache/spark/sql/catalyst/analysis/CheckViews.scala:64

            _,
            _,
            _,
            _,
            replace,
            _,
            _) =>
        verifyColumnCount(resolvedIdent, columnAliases, query)
        SchemaUtils.checkColumnNameDuplication(
          query.schema.fieldNames.toIndexedSeq,
          SQLConf.get.resolver)
        if (replace) {
          val viewIdent: Seq[String] =
            resolvedIdent.catalog.name() +: resolvedIdent.identifier.asMultipartIdentifier
          checkCyclicViewReference(viewIdent, query, Seq(viewIdent))
        }

      case AlterViewAs(ResolvedV2View(_, _), _, _) =>
        throw new IcebergAnalysisException(
          "ALTER VIEW <viewName> AS is not supported. Use CREATE OR REPLACE VIEW instead")

      case _ => // OK
    }
  }

  private def verifyColumnCount(
      ident: ResolvedIdentifier,
      columns: Seq[String],
      query: LogicalPlan): Unit = {
    if (columns.nonEmpty) {
      if (columns.length > query.output.length) {
        throw new AnalysisException(
          errorClass = "CREATE_VIEW_COLUMN_ARITY_MISMATCH.NOT_ENOUGH_DATA_COLUMNS",
          messageParameters = Map(
            "viewName" -> String.format("%s.%s", ident.catalog.name(), ident.identifier),
            "viewColumns" -> columns.mkString(", "),
            "dataColumns" -> query.output.map(c => c.name).mkString(", ")))

View on GitHub (pinned to 86d9c8fc54)

Solutions

Use `CREATE OR REPLACE VIEW <viewName> AS SELECT ...` instead of ALTER VIEW ... AS
Update migration scripts/templates to translate ALTER VIEW AS into CREATE OR REPLACE VIEW
If only metadata changes are needed (not the query), use ALTER VIEW RENAME TO or view properties commands as appropriate

Example fix

// before
ALTER VIEW my_view AS SELECT id, name FROM my_table
// after
CREATE OR REPLACE VIEW my_view AS SELECT id, name FROM my_table

Defensive patterns

Strategy: validation

Validate before calling

// rewrite DDL before execution
val rewritten = sqlText.replaceAll("(?i)\\bALTER\\s+VIEW\\s+(\\S+)\\s+AS\\b", "CREATE OR REPLACE VIEW $1 AS")

Try / catch

try { spark.sql(sqlText) } catch { case e: IcebergAnalysisException if e.getMessage.contains("ALTER VIEW") => spark.sql(toCreateOrReplace(sqlText)) }

Prevention

Use CREATE OR REPLACE VIEW for redefinition of Iceberg views
Update migration scripts that emit ALTER VIEW AS
Document that Iceberg views don't support ALTER VIEW AS

When it happens

Trigger: Executing `ALTER VIEW <iceberg view name> AS SELECT ...` against a view registered through the Iceberg catalog/session catalog (ResolvedV2View), while the Iceberg Spark extensions are loaded.

Common situations: Migrating Spark scripts written for the built-in Spark views (where ALTER VIEW AS works) to Iceberg views; automated migration tools generating ALTER VIEW statements.

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/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/cb39d6af6fbf3ebf. Report an issue: GitHub.