Trait Catalog 

pub trait Catalog:
    Send
    + Sync
    + Debug {
    // Required methods
    fn name(&self) -> &str;
    fn create_namespace<'life0, 'life1, 'async_trait>(
        &'life0 self,
        namespace: &'life1 Namespace,
        properties: Option<HashMap<String, String>>,
    ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, String>, Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn drop_namespace<'life0, 'life1, 'async_trait>(
        &'life0 self,
        namespace: &'life1 Namespace,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn load_namespace<'life0, 'life1, 'async_trait>(
        &'life0 self,
        namespace: &'life1 Namespace,
    ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, String>, Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn update_namespace<'life0, 'life1, 'async_trait>(
        &'life0 self,
        namespace: &'life1 Namespace,
        updates: Option<HashMap<String, String>>,
        removals: Option<Vec<String>>,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn namespace_exists<'life0, 'life1, 'async_trait>(
        &'life0 self,
        namespace: &'life1 Namespace,
    ) -> Pin<Box<dyn Future<Output = Result<bool, Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn list_tabulars<'life0, 'life1, 'async_trait>(
        &'life0 self,
        namespace: &'life1 Namespace,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Identifier>, Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn list_namespaces<'life0, 'life1, 'async_trait>(
        &'life0 self,
        parent: Option<&'life1 str>,
    ) -> Pin<Box<dyn Future<Output = Result<Vec<Namespace>, Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn tabular_exists<'life0, 'life1, 'async_trait>(
        &'life0 self,
        identifier: &'life1 Identifier,
    ) -> Pin<Box<dyn Future<Output = Result<bool, Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn drop_table<'life0, 'life1, 'async_trait>(
        &'life0 self,
        identifier: &'life1 Identifier,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn drop_view<'life0, 'life1, 'async_trait>(
        &'life0 self,
        identifier: &'life1 Identifier,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn drop_materialized_view<'life0, 'life1, 'async_trait>(
        &'life0 self,
        identifier: &'life1 Identifier,
    ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn load_tabular<'life0, 'async_trait>(
        self: Arc<Self>,
        identifier: &'life0 Identifier,
    ) -> Pin<Box<dyn Future<Output = Result<Tabular, Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn create_table<'async_trait>(
        self: Arc<Self>,
        identifier: Identifier,
        create_table: CreateTable,
    ) -> Pin<Box<dyn Future<Output = Result<Table, Error>> + Send + 'async_trait>>
       where Self: 'async_trait;
    fn create_view<'async_trait>(
        self: Arc<Self>,
        identifier: Identifier,
        create_view: CreateView<Option<()>>,
    ) -> Pin<Box<dyn Future<Output = Result<View, Error>> + Send + 'async_trait>>
       where Self: 'async_trait;
    fn create_materialized_view<'async_trait>(
        self: Arc<Self>,
        identifier: Identifier,
        create_view: CreateMaterializedView,
    ) -> Pin<Box<dyn Future<Output = Result<MaterializedView, Error>> + Send + 'async_trait>>
       where Self: 'async_trait;
    fn update_table<'async_trait>(
        self: Arc<Self>,
        commit: CommitTable,
    ) -> Pin<Box<dyn Future<Output = Result<Table, Error>> + Send + 'async_trait>>
       where Self: 'async_trait;
    fn update_view<'async_trait>(
        self: Arc<Self>,
        commit: CommitView<Option<()>>,
    ) -> Pin<Box<dyn Future<Output = Result<View, Error>> + Send + 'async_trait>>
       where Self: 'async_trait;
    fn update_materialized_view<'async_trait>(
        self: Arc<Self>,
        commit: CommitView<FullIdentifier>,
    ) -> Pin<Box<dyn Future<Output = Result<MaterializedView, Error>> + Send + 'async_trait>>
       where Self: 'async_trait;
    fn register_table<'life0, 'async_trait>(
        self: Arc<Self>,
        identifier: Identifier,
        metadata_location: &'life0 str,
    ) -> Pin<Box<dyn Future<Output = Result<Table, Error>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
}

A trait representing an Iceberg catalog that manages tables, views, and namespaces.

The Catalog trait provides methods to:

• Create, update, and delete namespaces
• Create, load, and drop tables and views
• List available tables and namespaces
• Manage table and view metadata
• Access object storage

Implementations must be Send + Sync for concurrent access and Debug for logging/debugging.

Required Methods

fn name(&self) -> &str

Returns the name of this catalog.

The catalog name is a unique identifier used to:

• Distinguish between multiple catalogs in a catalog list
• Reference this catalog in configuration
• Identify the catalog in logging and error messages

fn create_namespace<'life0, 'life1, 'async_trait>( &'life0 self, namespace: &'life1 Namespace, properties: Option<HashMap<String, String>>, ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, String>, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Creates a new namespace in the catalog with optional properties.

Arguments

• namespace - The namespace to create
• properties - Optional key-value properties to associate with the namespace

Returns

• Result<HashMap<String, String>, Error> - The namespace properties after creation

Errors

Returns an error if:

• The namespace already exists
• The namespace name is invalid
• The catalog fails to create the namespace
• Properties cannot be set

fn drop_namespace<'life0, 'life1, 'async_trait>( &'life0 self, namespace: &'life1 Namespace, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Removes a namespace and all its properties from the catalog.

Arguments

• namespace - The namespace to remove

Returns

• Result<(), Error> - Ok if the namespace was successfully removed

Errors

Returns an error if:

• The namespace doesn’t exist
• The namespace contains tables or views
• The catalog fails to remove the namespace

fn load_namespace<'life0, 'life1, 'async_trait>( &'life0 self, namespace: &'life1 Namespace, ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, String>, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Loads a namespace’s properties from the catalog.

Arguments

• namespace - The namespace to load properties for

Returns

• Result<HashMap<String, String>, Error> - The namespace properties if found

Errors

Returns an error if:

• The namespace doesn’t exist
• The catalog fails to load the namespace properties
• The properties cannot be deserialized

fn update_namespace<'life0, 'life1, 'async_trait>( &'life0 self, namespace: &'life1 Namespace, updates: Option<HashMap<String, String>>, removals: Option<Vec<String>>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Updates a namespace’s properties by applying updates and removals.

Arguments

• namespace - The namespace to update
• updates - Optional map of property key-value pairs to add or update
• removals - Optional list of property keys to remove

Returns

• Result<(), Error> - Ok if the namespace was successfully updated

Errors

Returns an error if:

• The namespace doesn’t exist
• The properties cannot be updated
• The catalog fails to persist the changes

fn namespace_exists<'life0, 'life1, 'async_trait>( &'life0 self, namespace: &'life1 Namespace, ) -> Pin<Box<dyn Future<Output = Result<bool, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Checks if a namespace exists in the catalog.

Arguments

• namespace - The namespace to check for existence

Returns

• Result<bool, Error> - True if the namespace exists, false otherwise

Errors

Returns an error if:

• The catalog cannot be accessed
• The namespace check operation fails

fn list_tabulars<'life0, 'life1, 'async_trait>( &'life0 self, namespace: &'life1 Namespace, ) -> Pin<Box<dyn Future<Output = Result<Vec<Identifier>, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Lists all tables, views, and materialized views in the given namespace.

Arguments

• namespace - The namespace to list tabular objects from

Returns

• Result<Vec<Identifier>, Error> - List of identifiers for all tabular objects

Errors

Returns an error if:

• The namespace doesn’t exist
• The catalog cannot be accessed
• The listing operation fails

fn list_namespaces<'life0, 'life1, 'async_trait>( &'life0 self, parent: Option<&'life1 str>, ) -> Pin<Box<dyn Future<Output = Result<Vec<Namespace>, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Lists all namespaces under an optional parent namespace.

Arguments

• parent - Optional parent namespace to list children under. If None, lists top-level namespaces.

Returns

• Result<Vec<Namespace>, Error> - List of namespace objects

Errors

Returns an error if:

• The parent namespace doesn’t exist (if specified)
• The catalog cannot be accessed
• The listing operation fails

fn tabular_exists<'life0, 'life1, 'async_trait>( &'life0 self, identifier: &'life1 Identifier, ) -> Pin<Box<dyn Future<Output = Result<bool, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Checks if a table, view, or materialized view exists in the catalog.

Arguments

• identifier - The identifier of the tabular object to check

Returns

• Result<bool, Error> - True if the tabular object exists, false otherwise

Errors

Returns an error if:

• The namespace doesn’t exist
• The catalog cannot be accessed
• The existence check operation fails

fn drop_table<'life0, 'life1, 'async_trait>( &'life0 self, identifier: &'life1 Identifier, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Drops a table from the catalog and deletes all associated data and metadata files.

Arguments

• identifier - The identifier of the table to drop

Returns

• Result<(), Error> - Ok if the table was successfully dropped

Errors

Returns an error if:

• The table doesn’t exist
• The table is locked or in use
• The catalog fails to delete the table metadata
• The data files cannot be deleted

fn drop_view<'life0, 'life1, 'async_trait>( &'life0 self, identifier: &'life1 Identifier, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Drops a view from the catalog and deletes its metadata.

Arguments

• identifier - The identifier of the view to drop

Returns

• Result<(), Error> - Ok if the view was successfully dropped

Errors

Returns an error if:

• The view doesn’t exist
• The view is in use
• The catalog fails to delete the view metadata

fn drop_materialized_view<'life0, 'life1, 'async_trait>( &'life0 self, identifier: &'life1 Identifier, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Drops a materialized view from the catalog and deletes its metadata and data files.

Arguments

• identifier - The identifier of the materialized view to drop

Returns

• Result<(), Error> - Ok if the materialized view was successfully dropped

Errors

Returns an error if:

• The materialized view doesn’t exist
• The materialized view is in use
• The catalog fails to delete the view metadata
• The associated data files cannot be deleted

fn load_tabular<'life0, 'async_trait>( self: Arc<Self>, identifier: &'life0 Identifier, ) -> Pin<Box<dyn Future<Output = Result<Tabular, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Loads a table, view, or materialized view from the catalog.

Arguments

• identifier - The identifier of the tabular object to load

Returns

• Result<Tabular, Error> - The loaded tabular object wrapped in an enum

Errors

Returns an error if:

• The tabular object doesn’t exist
• The metadata cannot be loaded
• The metadata is invalid or corrupted
• The catalog cannot be accessed

fn create_table<'async_trait>( self: Arc<Self>, identifier: Identifier, create_table: CreateTable, ) -> Pin<Box<dyn Future<Output = Result<Table, Error>> + Send + 'async_trait>>

where Self: 'async_trait,

Creates a new table in the catalog with the specified configuration.

Arguments

• identifier - The identifier for the new table
• create_table - Configuration for the table creation including schema, partitioning, etc.

Returns

• Result<Table, Error> - The newly created table object

Errors

Returns an error if:

• The table already exists
• The namespace doesn’t exist
• The schema is invalid
• The catalog fails to create the table metadata
• The table location cannot be initialized

fn create_view<'async_trait>( self: Arc<Self>, identifier: Identifier, create_view: CreateView<Option<()>>, ) -> Pin<Box<dyn Future<Output = Result<View, Error>> + Send + 'async_trait>>

where Self: 'async_trait,

Creates a new view in the catalog with the specified configuration.

Arguments

• identifier - The identifier for the new view
• create_view - Configuration for the view creation including view definition and properties

Returns

• Result<View, Error> - The newly created view object

Errors

Returns an error if:

• The view already exists
• The namespace doesn’t exist
• The view definition is invalid
• The catalog fails to create the view metadata

fn create_materialized_view<'async_trait>( self: Arc<Self>, identifier: Identifier, create_view: CreateMaterializedView, ) -> Pin<Box<dyn Future<Output = Result<MaterializedView, Error>> + Send + 'async_trait>>

where Self: 'async_trait,

Creates a new materialized view in the catalog with the specified configuration.

Arguments

• identifier - The identifier for the new materialized view
• create_view - Configuration for the materialized view creation including view definition, storage properties, and refresh policies

Returns

• Result<MaterializedView, Error> - The newly created materialized view object

Errors

Returns an error if:

• The materialized view already exists
• The namespace doesn’t exist
• The view definition is invalid
• The catalog fails to create the view metadata
• The storage location cannot be initialized

fn update_table<'async_trait>( self: Arc<Self>, commit: CommitTable, ) -> Pin<Box<dyn Future<Output = Result<Table, Error>> + Send + 'async_trait>>

where Self: 'async_trait,

Updates a table’s metadata by applying the specified commit operation.

Arguments

• commit - The commit operation containing metadata updates to apply

Returns

• Result<Table, Error> - The updated table object

Errors

Returns an error if:

• The table doesn’t exist
• The table is locked by another operation
• The commit operation is invalid
• The catalog fails to update the metadata
• Concurrent modifications conflict with this update

fn update_view<'async_trait>( self: Arc<Self>, commit: CommitView<Option<()>>, ) -> Pin<Box<dyn Future<Output = Result<View, Error>> + Send + 'async_trait>>

where Self: 'async_trait,

Updates a view’s metadata by applying the specified commit operation.

Arguments

• commit - The commit operation containing metadata updates to apply

Returns

• Result<View, Error> - The updated view object

Errors

Returns an error if:

• The view doesn’t exist
• The view is locked by another operation
• The commit operation is invalid
• The catalog fails to update the metadata
• Concurrent modifications conflict with this update

fn update_materialized_view<'async_trait>( self: Arc<Self>, commit: CommitView<FullIdentifier>, ) -> Pin<Box<dyn Future<Output = Result<MaterializedView, Error>> + Send + 'async_trait>>

where Self: 'async_trait,

Updates a materialized view’s metadata by applying the specified commit operation.

Arguments

• commit - The commit operation containing metadata updates to apply

Returns

• Result<MaterializedView, Error> - The updated materialized view object

Errors

Returns an error if:

• The materialized view doesn’t exist
• The materialized view is locked by another operation
• The commit operation is invalid
• The catalog fails to update the metadata
• Concurrent modifications conflict with this update
• The underlying storage cannot be updated

fn register_table<'life0, 'async_trait>( self: Arc<Self>, identifier: Identifier, metadata_location: &'life0 str, ) -> Pin<Box<dyn Future<Output = Result<Table, Error>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Registers an existing table in the catalog using its metadata location.

Arguments

• identifier - The identifier to register the table under
• metadata_location - Location of the table’s metadata file

Returns

• Result<Table, Error> - The registered table object

Errors

Returns an error if:

• A table already exists with the given identifier
• The metadata location is invalid or inaccessible
• The metadata file cannot be read or parsed
• The catalog fails to register the table

Implementors