Package org.apache.iceberg.catalog

Interface Catalog

All Known Implementing Classes:
BaseMetastoreCatalog, BaseMetastoreViewCatalog, BaseSessionCatalog.AsCatalog, CachingCatalog, DynamoDbCatalog, EcsCatalog, GlueCatalog, HadoopCatalog, HiveCatalog, InMemoryCatalog, JdbcCatalog, NessieCatalog, RESTCatalog, SnowflakeCatalog
public interface Catalog
A Catalog API for table create, drop, and load operations.

  • Method Details

    • name

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

    • listTables

      List<TableIdentifier> listTables(Namespace namespace)
      Return all the identifiers under this namespace.
      Parameters:
      namespace - a namespace
      Returns:
      a list of identifiers for tables
      Throws:
      NoSuchNamespaceException - if the namespace is not found

    • createTable

      default Table createTable(TableIdentifier identifier, Schema schema, PartitionSpec spec, String location, Map<String,String> properties)
      Create a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      spec - a partition spec
      location - a location for the table; leave null if unspecified
      properties - a string map of table properties
      Returns:
      a Table instance
      Throws:
      AlreadyExistsException - if the table already exists

    • createTable

      default Table createTable(TableIdentifier identifier, Schema schema, PartitionSpec spec, Map<String,String> properties)
      Create a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      spec - a partition spec
      properties - a string map of table properties
      Returns:
      a Table instance
      Throws:
      AlreadyExistsException - if the table already exists

    • createTable

      default Table createTable(TableIdentifier identifier, Schema schema, PartitionSpec spec)
      Create a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      spec - a partition spec
      Returns:
      a Table instance
      Throws:
      AlreadyExistsException - if the table already exists

    • createTable

      default Table createTable(TableIdentifier identifier, Schema schema)
      Create an unpartitioned table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      Returns:
      a Table instance
      Throws:
      AlreadyExistsException - if the table already exists

    • newCreateTableTransaction

      default Transaction newCreateTableTransaction(TableIdentifier identifier, Schema schema, PartitionSpec spec, String location, Map<String,String> properties)
      Start a transaction to create a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      spec - a partition spec
      location - a location for the table; leave null if unspecified
      properties - a string map of table properties
      Returns:
      a Transaction to create the table
      Throws:
      AlreadyExistsException - if the table already exists

    • newCreateTableTransaction

      default Transaction newCreateTableTransaction(TableIdentifier identifier, Schema schema, PartitionSpec spec, Map<String,String> properties)
      Start a transaction to create a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      spec - a partition spec
      properties - a string map of table properties
      Returns:
      a Transaction to create the table
      Throws:
      AlreadyExistsException - if the table already exists

    • newCreateTableTransaction

      default Transaction newCreateTableTransaction(TableIdentifier identifier, Schema schema, PartitionSpec spec)
      Start a transaction to create a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      spec - a partition spec
      Returns:
      a Transaction to create the table
      Throws:
      AlreadyExistsException - if the table already exists

    • newCreateTableTransaction

      default Transaction newCreateTableTransaction(TableIdentifier identifier, Schema schema)
      Start a transaction to create a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      Returns:
      a Transaction to create the table
      Throws:
      AlreadyExistsException - if the table already exists

    • newReplaceTableTransaction

      default Transaction newReplaceTableTransaction(TableIdentifier identifier, Schema schema, PartitionSpec spec, String location, Map<String,String> properties, boolean orCreate)
      Start a transaction to replace a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      spec - a partition spec
      location - a location for the table; leave null if unspecified
      properties - a string map of table properties
      orCreate - whether to create the table if not exists
      Returns:
      a Transaction to replace the table
      Throws:
      NoSuchTableException - if the table doesn't exist and orCreate is false

    • newReplaceTableTransaction

      default Transaction newReplaceTableTransaction(TableIdentifier identifier, Schema schema, PartitionSpec spec, Map<String,String> properties, boolean orCreate)
      Start a transaction to replace a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      spec - a partition spec
      properties - a string map of table properties
      orCreate - whether to create the table if not exists
      Returns:
      a Transaction to replace the table
      Throws:
      NoSuchTableException - if the table doesn't exist and orCreate is false

    • newReplaceTableTransaction

      default Transaction newReplaceTableTransaction(TableIdentifier identifier, Schema schema, PartitionSpec spec, boolean orCreate)
      Start a transaction to replace a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      spec - a partition spec
      orCreate - whether to create the table if not exists
      Returns:
      a Transaction to replace the table
      Throws:
      NoSuchTableException - if the table doesn't exist and orCreate is false

    • newReplaceTableTransaction

      default Transaction newReplaceTableTransaction(TableIdentifier identifier, Schema schema, boolean orCreate)
      Start a transaction to replace a table.
      Parameters:
      identifier - a table identifier
      schema - a schema
      orCreate - whether to create the table if not exists
      Returns:
      a Transaction to replace the table
      Throws:
      NoSuchTableException - if the table doesn't exist and orCreate is false

    • tableExists

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

    • dropTable

      default boolean dropTable(TableIdentifier identifier)
      Drop a table and delete all data and metadata files.
      Parameters:
      identifier - a table identifier
      Returns:
      true if the table was dropped, false if the table did not exist

    • dropTable

      boolean dropTable(TableIdentifier identifier, boolean purge)
      Drop a table; optionally delete data and metadata files.

      If purge is set to true the implementation should delete all data and metadata files.

      Parameters:
      identifier - a table identifier
      purge - if true, delete all data and metadata files in the table
      Returns:
      true if the table was dropped, false if the table did not exist

    • renameTable

      void renameTable(TableIdentifier from, TableIdentifier to)
      Rename a table.
      Parameters:
      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

    • loadTable

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

    • invalidateTable

      default void invalidateTable(TableIdentifier identifier)
      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:
      identifier - a table identifier

    • registerTable

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

    • buildTable

      default Catalog.TableBuilder buildTable(TableIdentifier identifier, Schema schema)
      /** Instantiate a builder to either create a table or start a create/replace transaction.
      Parameters:
      identifier - a table identifier
      schema - a schema
      Returns:
      the builder to create a table or start a create/replace transaction

    • initialize

      default void initialize(String name, Map<String,String> properties)
      Initialize a catalog given a custom name and a map of catalog properties.

      A custom Catalog implementation must have a no-arg constructor. A compute engine like Spark or Flink will first initialize the catalog without any arguments, and then call this method to complete catalog initialization with properties passed into the engine.

      Parameters:
      name - a custom name for the catalog
      properties - catalog properties