Implementation:Apache Paimon CatalogException

Knowledge Sources	Apache_Paimon
Domains	Error Handling, Catalog Management
Last Updated	2026-02-08 00:00 GMT

Overview

CatalogException provides a comprehensive exception hierarchy for catalog operations including database, table, view, function, column, definition, and dialect errors.

Description

The CatalogException module defines a hierarchical set of exception classes for handling errors in catalog operations. The base CatalogException class serves as the root for all catalog-related errors. The exception hierarchy covers existence checks (NotExist vs AlreadyExist), permission errors (NoPermission), and applies to multiple catalog entity types.

The module organizes exceptions into pairs for each entity type: databases (DatabaseNotExistException, DatabaseAlreadyExistException, DatabaseNoPermissionException), tables (TableNotExistException, TableAlreadyExistException, TableNoPermissionException), views (ViewNotExistException, ViewAlreadyExistException), functions (FunctionNotExistException, FunctionAlreadyExistException), and columns (ColumnNotExistException, ColumnAlreadyExistException).

Additional specialized exceptions handle metadata definitions (DefinitionNotExistException, DefinitionAlreadyExistException) and SQL dialects (DialectNotExistException, DialectAlreadyExistException). Most exceptions store the relevant Identifier to provide context about which database.table combination caused the error. This structured approach enables precise error handling and user-friendly error messages throughout the catalog layer.

Usage

Use CatalogException classes when implementing catalog operations that need to signal existence conflicts, missing resources, or permission errors with proper context including database and table identifiers.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-python/pypaimon/catalog/catalog_exception.py

Signature

class CatalogException(Exception):
    """Base catalog exception"""

class DatabaseNotExistException(CatalogException):
    def __init__(self, database: str):
        pass

class DatabaseAlreadyExistException(CatalogException):
    def __init__(self, database: str):
        pass

class DatabaseNoPermissionException(CatalogException):
    def __init__(self, database: str):
        pass

class TableNotExistException(CatalogException):
    def __init__(self, identifier: Identifier):
        pass

class TableAlreadyExistException(CatalogException):
    def __init__(self, identifier: Identifier):
        pass

class TableNoPermissionException(CatalogException):
    def __init__(self, identifier: Identifier):
        pass

class ViewNotExistException(CatalogException):
    def __init__(self, identifier: Identifier):
        pass

class ViewAlreadyExistException(CatalogException):
    def __init__(self, identifier: Identifier):
        pass

class FunctionNotExistException(CatalogException):
    def __init__(self, identifier: Identifier):
        pass

class FunctionAlreadyExistException(CatalogException):
    def __init__(self, identifier: Identifier):
        pass

class ColumnNotExistException(CatalogException):
    def __init__(self, column: str):
        pass

class ColumnAlreadyExistException(CatalogException):
    def __init__(self, column: str):
        pass

class DefinitionNotExistException(CatalogException):
    def __init__(self, identifier: Identifier, name: str):
        pass

class DefinitionAlreadyExistException(CatalogException):
    def __init__(self, identifier: Identifier, name: str):
        pass

class DialectNotExistException(CatalogException):
    def __init__(self, identifier: Identifier, dialect: str):
        pass

class DialectAlreadyExistException(CatalogException):
    def __init__(self, identifier: Identifier, dialect: str):
        pass

Import

from pypaimon.catalog.catalog_exception import (
    CatalogException, DatabaseNotExistException,
    TableNotExistException, TableAlreadyExistException,
    ViewNotExistException, FunctionNotExistException,
    ColumnNotExistException, DatabaseNoPermissionException
)

I/O Contract

Inputs

Name	Type	Required	Description
database	str	Yes	Database name for database exceptions
identifier	Identifier	Yes	Table identifier for table/view/function exceptions
column	str	Yes	Column name for column exceptions
name	str	Yes	Definition name for definition exceptions
dialect	str	Yes	Dialect name for dialect exceptions

Outputs

Name	Type	Description
exception	CatalogException	Raised exception with descriptive message

Usage Examples

from pypaimon.catalog.catalog_exception import (
    DatabaseNotExistException, TableAlreadyExistException,
    TableNotExistException, ColumnNotExistException
)
from pypaimon.common.identifier import Identifier

# Handle database not found
def get_database(name: str):
    if not database_exists(name):
        raise DatabaseNotExistException(name)
    return load_database(name)

# Handle table already exists
def create_table(identifier: Identifier):
    if table_exists(identifier):
        raise TableAlreadyExistException(identifier)
    # Create table...

# Handle table not found
try:
    identifier = Identifier.create("my_db", "my_table")
    table = load_table(identifier)
except TableNotExistException as e:
    print(f"Table not found: {e.identifier.get_full_name()}")
    # Table my_db.my_table does not exist

# Handle column errors
try:
    add_column("new_column")
except ColumnNotExistException as e:
    print(f"Column does not exist: {e.column}")

# Comprehensive error handling
try:
    # Catalog operations
    pass
except DatabaseNotExistException as e:
    print(f"Database '{e.database}' not found")
except TableNotExistException as e:
    print(f"Table '{e.identifier.get_full_name()}' not found")
except TableAlreadyExistException as e:
    print(f"Table '{e.identifier.get_full_name()}' already exists")
except CatalogException as e:
    print(f"Catalog error: {e}")

# Check exception attributes
try:
    identifier = Identifier.create("db", "table")
    raise TableNotExistException(identifier)
except TableNotExistException as e:
    assert e.identifier.get_database_name() == "db"
    assert e.identifier.get_table_name() == "table"

Related Pages

• Principle:Apache_Paimon_Catalog_Object_Model