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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	SessionCatalog.SessionContext	Context for a session.

Method Summary

Modifier and Type	Method	Description
Catalog.TableBuilder	buildTable(SessionCatalog.SessionContext context, TableIdentifier ident, Schema schema)	Create a builder to create a table or start a create/replace transaction.
default void	createNamespace(SessionCatalog.SessionContext context, Namespace namespace)	Create a namespace in the catalog.
void	createNamespace(SessionCatalog.SessionContext context, Namespace namespace, java.util.Map<java.lang.String,java.lang.String> metadata)	Create a namespace in the catalog.
boolean	dropNamespace(SessionCatalog.SessionContext context, Namespace namespace)	Drop a namespace.
boolean	dropTable(SessionCatalog.SessionContext context, TableIdentifier ident)	Drop a table, without requesting that files are immediately deleted.
void	initialize(java.lang.String name, java.util.Map<java.lang.String,java.lang.String> properties)	Initialize given a custom name and a map of catalog properties.
void	invalidateTable(SessionCatalog.SessionContext context, TableIdentifier ident)	Invalidate cached table metadata from current catalog.
default java.util.List<Namespace>	listNamespaces(SessionCatalog.SessionContext context)	List top-level namespaces from the catalog.
java.util.List<Namespace>	listNamespaces(SessionCatalog.SessionContext context, Namespace namespace)	List child namespaces from the namespace.
java.util.List<TableIdentifier>	listTables(SessionCatalog.SessionContext context, Namespace namespace)	Return all the identifiers under this namespace.
java.util.Map<java.lang.String,java.lang.String>	loadNamespaceMetadata(SessionCatalog.SessionContext context, Namespace namespace)	Load metadata properties for a namespace.
Table	loadTable(SessionCatalog.SessionContext context, TableIdentifier ident)	Load a table.
java.lang.String	name()	Return the name for this catalog.
default boolean	namespaceExists(SessionCatalog.SessionContext context, Namespace namespace)	Checks whether the Namespace exists.
java.util.Map<java.lang.String,java.lang.String>	properties()	Return the properties for this catalog.
boolean	purgeTable(SessionCatalog.SessionContext context, TableIdentifier ident)	Drop a table and request that files are immediately deleted.
Table	registerTable(SessionCatalog.SessionContext context, TableIdentifier ident, java.lang.String metadataFileLocation)	Register a table if it does not exist.
void	renameTable(SessionCatalog.SessionContext context, TableIdentifier from, TableIdentifier to)	Rename a table.
default boolean	tableExists(SessionCatalog.SessionContext context, TableIdentifier ident)	Check whether table exists.
boolean	updateNamespaceMetadata(SessionCatalog.SessionContext context, Namespace namespace, java.util.Map<java.lang.String,java.lang.String> updates, java.util.Set<java.lang.String> removals)	Set a collection of properties on a namespace in the catalog.

Method Detail

initialize

void initialize(java.lang.String name,
                java.util.Map<java.lang.String,java.lang.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

java.lang.String name()

Return the name for this catalog.

Returns:

this catalog's name

properties

java.util.Map<java.lang.String,java.lang.String> properties()

Return the properties for this catalog.

Returns:

this catalog's config properties

listTables

java.util.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,
                    java.lang.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:

java.lang.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

java.lang.UnsupportedOperationException - If create is not a supported operation

createNamespace

void createNamespace(SessionCatalog.SessionContext context,
                     Namespace namespace,
                     java.util.Map<java.lang.String,java.lang.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

java.lang.UnsupportedOperationException - If create is not a supported operation

listNamespaces

default java.util.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

java.util.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

java.util.Map<java.lang.String,java.lang.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,
                                java.util.Map<java.lang.String,java.lang.String> updates,
                                java.util.Set<java.lang.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)

java.lang.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