Package org.apache.spark.sql.connector.catalog

Interface ViewCatalog

All Superinterfaces:
CatalogPlugin
All Known Subinterfaces:
RelationCatalog
@Evolving public interface ViewCatalog extends CatalogPlugin
Catalog API for connectors that expose views.

Connectors that expose only views implement this interface. Connectors that expose both tables and views must implement RelationCatalog (which extends both this interface and TableCatalog and adds the cross-cutting contract for the combined case); the methods on this interface remain view-only -- they do not interact with tables.

The presence of ViewCatalog on the catalog plugin is the signal that it supports views; there is no capability flag to declare.

Since:
4.2.0

  • Method Details

    • listViews

      Identifier[] listViews(String[] namespace) throws org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException
      List the views in a namespace from the catalog.
      Parameters:
      namespace - a multi-part namespace
      Returns:
      an array of identifiers for views
      Throws:
      org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException - if the namespace does not exist (optional)

    • loadView

      View loadView(Identifier ident) throws org.apache.spark.sql.catalyst.analysis.NoSuchViewException
      Load view metadata by identifier.
      Parameters:
      ident - a view identifier
      Returns:
      the view metadata
      Throws:
      org.apache.spark.sql.catalyst.analysis.NoSuchViewException - if the view does not exist

    • viewExists

      default boolean viewExists(Identifier ident)
      Test whether a view exists.

      The default implementation calls loadView(org.apache.spark.sql.connector.catalog.Identifier) and catches NoSuchViewException. Catalogs that can answer existence cheaply should override.

      Parameters:
      ident - a view identifier
      Returns:
      true if a view exists at ident, false otherwise

    • invalidateView

      default void invalidateView(Identifier ident)
      Invalidate cached metadata for a view.

      If the view is currently cached, drop the cached entry; otherwise do nothing. This must not issue remote calls.

      Parameters:
      ident - a view identifier

    • createView

      View createView(Identifier ident, View info) throws org.apache.spark.sql.catalyst.analysis.ViewAlreadyExistsException, org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException
      Create a view.
      Parameters:
      ident - the view identifier
      info - the view metadata
      Returns:
      the metadata of the newly created view; may equal info
      Throws:
      org.apache.spark.sql.catalyst.analysis.ViewAlreadyExistsException - if a view already exists at ident
      org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException - if the identifier's namespace does not exist (optional)

    • replaceView

      View replaceView(Identifier ident, View info) throws org.apache.spark.sql.catalyst.analysis.NoSuchViewException
      Atomically replace an existing view's metadata.

      Used by ALTER VIEW ... AS. Implementations should commit the new metadata atomically; views carry no data, so a single transactional metastore call (or equivalent) is sufficient -- there is no separate staging API.

      Parameters:
      ident - the view identifier
      info - the new view metadata
      Returns:
      the metadata of the replaced view; may equal info
      Throws:
      org.apache.spark.sql.catalyst.analysis.NoSuchViewException - if no view exists at ident

    • createOrReplaceView

      default View createOrReplaceView(Identifier ident, View info) throws org.apache.spark.sql.catalyst.analysis.ViewAlreadyExistsException, org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException
      Create a view if one does not exist at ident, or atomically replace it if one does.

      Used by CREATE OR REPLACE VIEW. The default implementation calls replaceView(org.apache.spark.sql.connector.catalog.Identifier, org.apache.spark.sql.connector.catalog.View), falling back to createView(org.apache.spark.sql.connector.catalog.Identifier, org.apache.spark.sql.connector.catalog.View) on NoSuchViewException. The fallback is non-atomic across the two calls (a concurrent drop or create can race), so catalogs that can answer the upsert in a single transactional call should override this method to collapse to one RPC and to make the swap atomic.

      Parameters:
      ident - the view identifier
      info - the view metadata
      Returns:
      the metadata of the created or replaced view; may equal info
      Throws:
      org.apache.spark.sql.catalyst.analysis.ViewAlreadyExistsException - if ident cannot host this view -- either a concurrent CREATE VIEW won the race in the default impl's gap between replaceView(org.apache.spark.sql.connector.catalog.Identifier, org.apache.spark.sql.connector.catalog.View) and the fallback createView(org.apache.spark.sql.connector.catalog.Identifier, org.apache.spark.sql.connector.catalog.View), or, in a RelationCatalog, a table sits at ident
      org.apache.spark.sql.catalyst.analysis.NoSuchNamespaceException - if the identifier's namespace does not exist (optional)

    • dropView

      boolean dropView(Identifier ident)
      Drop a view.
      Parameters:
      ident - a view identifier
      Returns:
      true if a view was dropped, false otherwise

    • renameView

      void renameView(Identifier oldIdent, Identifier newIdent) throws org.apache.spark.sql.catalyst.analysis.NoSuchViewException, org.apache.spark.sql.catalyst.analysis.ViewAlreadyExistsException
      Rename a view.

      If the catalog supports tables and contains a table at the new identifier, this must throw ViewAlreadyExistsException. If the source identifier resolves to a table rather than a view, this must throw NoSuchViewException. The cross-type contract for catalogs that expose both tables and views lives on RelationCatalog.

      Parameters:
      oldIdent - the view identifier of the existing view to rename
      newIdent - the new view identifier
      Throws:
      org.apache.spark.sql.catalyst.analysis.NoSuchViewException - if no view exists at oldIdent
      org.apache.spark.sql.catalyst.analysis.ViewAlreadyExistsException - if a view (or, in a RelationCatalog, a table) already exists at newIdent