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

The Iceberg view extensions do not implement ALTER VIEW ... AS for Iceberg (v2) views; the CheckViews analysis rule intercepts AlterViewAs on ResolvedV2View and fails fast with this exception. Iceberg views are redefined with CREATE OR REPLACE VIEW instead of being altered in place.

Source

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

          case resolvedIdent @ ResolvedIdentifier(_: ViewCatalog, _) =>
            val viewIdent: Seq[String] =
              resolvedIdent.catalog.name() +: resolvedIdent.identifier.asMultipartIdentifier
            ViewHelper.verifyTemporaryObjectsNotExists(
              isTemporary = false,
              viewIdent,
              c.query,
              c.referredTempFunctions)
            ViewHelper.verifyAutoGeneratedAliasesNotExists(c.query, isTemporary = false, viewIdent)
            verifyColumnCount(resolvedIdent, c.columnAliases, c.query)
            if (c.replace) {
              checkCyclicViewReference(viewIdent, c.query, Seq(viewIdent))
            }

          case _ => // OK
        }

      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) {
      val viewNameParts = ident.catalog.name() +: ident.identifier.asMultipartIdentifier
      if (columns.length > query.output.length) {
        throw QueryCompilationErrors.cannotCreateViewNotEnoughColumnsError(
          viewNameParts,
          columns,
          query)
      } else if (columns.length < query.output.length) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

Replace the statement with CREATE OR REPLACE VIEW <viewName> AS <query>.
If you only need to change the definition occasionally, drop and recreate the view with CREATE OR REPLACE in one idempotent statement.
Keep ALTER VIEW usage limited to non-Iceberg (V1/temp) views where Spark supports it.

Example fix

-- before
ALTER VIEW my_view AS SELECT id, ts FROM my_table WHERE ts > '2024-01-01'
-- after
CREATE OR REPLACE VIEW my_view AS SELECT id, ts FROM my_table WHERE ts > '2024-01-01'

Defensive patterns

Strategy: try-catch

Try / catch

try {
  spark.sql(s"ALTER VIEW $name AS $query")
} catch {
  case e: IcebergAnalysisException if e.getMessage.contains("ALTER VIEW") =>
    spark.sql(s"CREATE OR REPLACE VIEW $name AS $query")
}

Prevention

Use CREATE OR REPLACE VIEW for Iceberg views everywhere
Keep ALTER VIEW only in scripts targeting Spark V1 temp views
Grep migration scripts for 'ALTER VIEW' before pointing them at Iceberg catalogs
Document view lifecycle in your team's DDL conventions

When it happens

Trigger: Running `ALTER VIEW <iceberg_view_name> AS <query>` where the view resolves to an Iceberg V2 view (created through the Iceberg catalog with view support enabled).

Common situations: Porting scripts written for Spark's built-in views (where ALTER VIEW AS works) to Iceberg views; migration tooling that assumes ALTER VIEW semantics across catalogs.

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/0ce4a5879314aae8. Report an issue: GitHub.