Package org.apache.iceberg.catalog

Interface SessionCatalog

All Known Implementing Classes:
BaseSessionCatalog, BaseViewSessionCatalog, RESTSessionCatalog
public interface SessionCatalog
A Catalog API for table and namespace operations that includes session context.

  • Method Details

    • initialize

      void initialize(String name, Map<String,String> properties)
      Initialize given a custom name and a map of catalog properties.
      Parameters:
      name - a custom name for the catalog
      properties - catalog properties

    • name

      String name()
      Return the name for this catalog.
      Returns:
      this catalog's name

    • properties

      Map<String,String> properties()
      Return the properties for this catalog.
      Returns:
      this catalog's config properties

    • listTables

      List<TableIdentifier> listTables(SessionCatalog.SessionContext context, Namespace namespace)
      Return all the identifiers under this namespace.
      Parameters:
      context - session context
      namespace - a namespace
      Returns:
      a list of identifiers for tables
      Throws:
      NoSuchNamespaceException - if the namespace does not exist

    • buildTable

      Catalog.TableBuilder buildTable(SessionCatalog.SessionContext context, TableIdentifier ident, Schema schema)
      Create a builder to create a table or start a create/replace transaction.
      Parameters:
      context - session context
      ident - a table identifier
      schema - a schema
      Returns:
      the builder to create a table or start a create/replace transaction

    • registerTable

      Table registerTable(SessionCatalog.SessionContext context, TableIdentifier ident, String metadataFileLocation)
      Register a table if it does not exist.
      Parameters:
      context - session context
      ident - a table identifier
      metadataFileLocation - the location of a metadata file
      Returns:
      a Table instance
      Throws:
      AlreadyExistsException - if the table already exists in the catalog.

    • tableExists

      default boolean tableExists(SessionCatalog.SessionContext context, TableIdentifier ident)
      Check whether table exists.
      Parameters:
      context - session context
      ident - a table identifier
      Returns:
      true if the table exists, false otherwise

    • loadTable

      Table loadTable(SessionCatalog.SessionContext context, TableIdentifier ident)
      Load a table.
      Parameters:
      context - session context
      ident - a table identifier
      Returns:
      instance of Table implementation referred by tableIdentifier
      Throws:
      NoSuchTableException - if the table does not exist

    • dropTable

      boolean dropTable(SessionCatalog.SessionContext context, TableIdentifier ident)
      Drop a table, without requesting that files are immediately deleted.

      Data and metadata files should be deleted according to the catalog's policy.

      Parameters:
      context - session context
      ident - a table identifier
      Returns:
      true if the table was dropped, false if the table did not exist

    • purgeTable

      boolean purgeTable(SessionCatalog.SessionContext context, TableIdentifier ident)
      Drop a table and request that files are immediately deleted.
      Parameters:
      context - session context
      ident - a table identifier
      Returns:
      true if the table was dropped and purged, false if the table did not exist
      Throws:
      UnsupportedOperationException - if immediate delete is not supported

    • renameTable

      void renameTable(SessionCatalog.SessionContext context, TableIdentifier from, TableIdentifier to)
      Rename a table.
      Parameters:
      context - session context
      from - identifier of the table to rename
      to - new table name
      Throws:
      NoSuchTableException - if the from table does not exist
      AlreadyExistsException - if the to table already exists

    • invalidateTable

      void invalidateTable(SessionCatalog.SessionContext context, TableIdentifier ident)
      Invalidate cached table metadata from current catalog.

      If the table is already loaded or cached, drop cached data. If the table does not exist or is not cached, do nothing.

      Parameters:
      context - session context
      ident - a table identifier

    • createNamespace

      default void createNamespace(SessionCatalog.SessionContext context, Namespace namespace)
      Create a namespace in the catalog.
      Parameters:
      context - session context
      namespace - a namespace
      Throws:
      AlreadyExistsException - If the namespace already exists
      UnsupportedOperationException - If create is not a supported operation

    • createNamespace

      void createNamespace(SessionCatalog.SessionContext context, Namespace namespace, Map<String,String> metadata)
      Create a namespace in the catalog.
      Parameters:
      context - session context
      namespace - a namespace
      metadata - a string Map of properties for the given namespace
      Throws:
      AlreadyExistsException - If the namespace already exists
      UnsupportedOperationException - If create is not a supported operation

    • listNamespaces

      default List<Namespace> listNamespaces(SessionCatalog.SessionContext context)
      List top-level namespaces from the catalog.

      If an object such as a table, view, or function exists, its parent namespaces must also exist and must be returned by this discovery method. For example, if table a.b.t exists, this method must return ["a"] in the result array.

      Parameters:
      context - session context
      Returns:
      a List of namespace Namespace names

    • listNamespaces

      List<Namespace> listNamespaces(SessionCatalog.SessionContext context, Namespace namespace)
      List child namespaces from the namespace.

      For two existing tables named 'a.b.c.table' and 'a.b.d.table', this method returns:

      • Given: Namespace.empty()
      • Returns: Namespace.of("a")
      • Given: Namespace.of("a")
      • Returns: Namespace.of("a", "b")
      • Given: Namespace.of("a", "b")
      • Returns: Namespace.of("a", "b", "c") and Namespace.of("a", "b", "d")
      • Given: Namespace.of("a", "b", "c")
      • Returns: empty list, because there are no child namespaces
      Parameters:
      context - session context
      namespace - a namespace
      Returns:
      a List of child Namespace names from the given namespace
      Throws:
      NoSuchNamespaceException - If the namespace does not exist (optional)

    • loadNamespaceMetadata

      Map<String,String> loadNamespaceMetadata(SessionCatalog.SessionContext context, Namespace namespace)
      Load metadata properties for a namespace.
      Parameters:
      context - session context
      namespace - a namespace
      Returns:
      a string map of properties for the given namespace
      Throws:
      NoSuchNamespaceException - If the namespace does not exist (optional)

    • dropNamespace

      boolean dropNamespace(SessionCatalog.SessionContext context, Namespace namespace)
      Drop a namespace. If the namespace exists and was dropped, this will return true.
      Parameters:
      context - session context
      namespace - a namespace
      Returns:
      true if the namespace was dropped, false otherwise.
      Throws:
      NamespaceNotEmptyException - If the namespace is not empty

    • updateNamespaceMetadata

      boolean updateNamespaceMetadata(SessionCatalog.SessionContext context, Namespace namespace, Map<String,String> updates, Set<String> removals)
      Set a collection of properties on a namespace in the catalog.

      Properties that are not in the given map are not modified or removed by this method.

      Parameters:
      context - session context
      namespace - a namespace
      updates - properties to set for the namespace
      removals - properties to remove from the namespace
      Throws:
      NoSuchNamespaceException - If the namespace does not exist (optional)
      UnsupportedOperationException - If namespace properties are not supported

    • namespaceExists

      default boolean namespaceExists(SessionCatalog.SessionContext context, Namespace namespace)
      Checks whether the Namespace exists.
      Parameters:
      context - session context
      namespace - a namespace
      Returns:
      true if the Namespace exists, false otherwise