Implementation:Apache Paimon Identifier Python

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

Overview

Identifier represents a fully qualified database object name in Apache Paimon, supporting database, table/object, and optional branch components with system table detection.

Description

The Identifier dataclass provides a structured representation of Paimon catalog object names, consisting of a required database name, a required object name (typically a table), and an optional branch name for branched table access. It uses the json_field decorator for JSON serialization compatibility, mapping to standard JSON field names.

The class supports multiple construction patterns: direct instantiation, the create() class method for simple database.table identifiers, and from_string() for parsing dot-separated identifier strings. The from_string() method handles both two-part (database.table) and three-part (database.table.branch) identifier formats, throwing ValueError for invalid formats.

Identifier provides accessor methods with clear semantics: get_database_name() and get_table_name() for the primary components, get_object_name() as an alias for table name, get_branch_name() for optional branch access, and get_full_name() which constructs the complete dot-separated identifier string. The is_system_table() method detects system tables by checking if the object name starts with '$', supporting Paimon's system table convention for metadata access.

Usage

Use Identifier when representing catalog objects in APIs, parsing user-provided table references, or constructing fully qualified names for database operations with proper validation and formatting.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-python/pypaimon/common/identifier.py

Signature

@dataclass
class Identifier:

    database: str = json_field("database", default=None)
    object: str = json_field("object", default=None)
    branch: Optional[str] = json_field("branch", default=None)

    @classmethod
    def create(cls, database: str, object: str) -> "Identifier":
        pass

    @classmethod
    def from_string(cls, full_name: str) -> "Identifier":
        pass

    def get_full_name(self) -> str:
        pass

    def get_database_name(self) -> str:
        pass

    def get_table_name(self) -> str:
        pass

    def get_object_name(self) -> str:
        pass

    def get_branch_name(self) -> Optional[str]:
        pass

    def is_system_table(self) -> bool:
        pass

Import

from pypaimon.common.identifier import Identifier

I/O Contract

Inputs

Name	Type	Required	Description
database	str	Yes	Database name
object	str	Yes	Object/table name
branch	str	No	Optional branch name
full_name	str	Yes	Dot-separated identifier string (for from_string)

Outputs

Name	Type	Description
identifier	Identifier	Constructed identifier instance
full_name	str	Dot-separated full identifier string
is_system	bool	Whether this is a system table

Usage Examples

from pypaimon.common.identifier import Identifier

# Create identifier using factory method
identifier = Identifier.create("my_database", "my_table")
print(identifier.get_full_name())  # "my_database.my_table"

# Parse from string
identifier = Identifier.from_string("sales.orders")
print(f"Database: {identifier.get_database_name()}")  # "sales"
print(f"Table: {identifier.get_table_name()}")  # "orders"

# Parse with branch
identifier = Identifier.from_string("db.table.branch")
print(f"Branch: {identifier.get_branch_name()}")  # "branch"
print(identifier.get_full_name())  # "db.table.branch"

# Direct instantiation
identifier = Identifier(
    database="analytics",
    object="user_events",
    branch="dev"
)

# Access components
print(identifier.get_database_name())  # "analytics"
print(identifier.get_table_name())  # "user_events"
print(identifier.get_object_name())  # "user_events" (alias)
print(identifier.get_branch_name())  # "dev"
print(identifier.get_full_name())  # "analytics.user_events.dev"

# Check for system tables
system_identifier = Identifier.create("db", "$snapshots")
if system_identifier.is_system_table():
    print("This is a system table")  # Prints this

normal_identifier = Identifier.create("db", "user_table")
if not normal_identifier.is_system_table():
    print("This is a normal table")  # Prints this

# Error handling
try:
    invalid = Identifier.from_string("invalid")  # Only one component
except ValueError as e:
    print(f"Error: {e}")

try:
    invalid = Identifier.from_string("a.b.c.d")  # Too many components
except ValueError as e:
    print(f"Error: {e}")

# Use in catalog operations
def load_table(identifier: Identifier):
    print(f"Loading table: {identifier.get_full_name()}")
    if identifier.is_system_table():
        print("  (system table)")
    # Load table logic...

identifier = Identifier.create("warehouse", "products")
load_table(identifier)

Related Pages

• Principle:Apache_Paimon_Catalog_Object_Model