apache/iceberg · error · AnalysisException

ALTER VIEW AS is not supported. Use CREATE OR REPLACE VIEW…

Error message

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

What it means

Iceberg's v3.5 Spark-extensions view checker rejects ALTER VIEW ... AS for Iceberg views (ResolvedV2View). Iceberg views do not support in-place query replacement via ALTER VIEW; the SQL dialect requires CREATE OR REPLACE VIEW to change a view's definition, so an AnalysisException is thrown during analysis.

Solutions

1. Rewrite the statement as CREATE OR REPLACE VIEW <viewName> AS <query>.
2. If you truly need ALTER VIEW semantics, use a Spark built-in (session-catalog) view instead of an Iceberg view.
3. Update migration tooling/ORM templates to emit CREATE OR REPLACE VIEW for Iceberg catalogs.

Example fix

// before
ALTER VIEW db.events AS SELECT * FROM events_v2
// after
CREATE OR REPLACE VIEW db.events AS SELECT * FROM events_v2

// Databricks/JDBC preflight: SHOW VIEWS IN db; treat Iceberg-catalog views as CREATE OR REPLACE only

def isIcebergView(ident: String): Boolean = ident.startsWith("iceberg_catalog.")  // route these to CREATE OR REPLACE VIEW, never ALTER VIEW

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

When it happens

Trigger: Executing `ALTER VIEW catalog.db.view AS SELECT ...` where the view is an Iceberg view registered through the Iceberg Spark catalog (matched by AlterViewAs(ResolvedV2View(_, _), _, _) in CheckViews.checkViews).

Common situations: Migrating scripts from built-in Spark views (where ALTER VIEW AS works) to Iceberg views; ORM/migration tools emitting ALTER VIEW; refactoring view SQL that previously targeted non-Iceberg 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

• ALTER VIEW AS is not supported. Use CREATE OR REPLACE VIEW…
• CREATE_VIEW_COLUMN_ARITY_MISMATCH.NOT_ENOUGH_DATA_COLUMNS
• ALTER TABLE contains multiple distribution clauses
• ALTER TABLE contains multiple distribution clauses
• ALTER TABLE contains multiple ordering clauses

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/79dc5151cdbd7d27. Report an issue: GitHub.

Appendix: source

Thrown at spark/v3.5/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 AnalysisException(
          "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)