Implementation:Apache Paimon Identifier

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

Overview

Identifier is a serializable class that uniquely identifies database objects in Apache Paimon's catalog system.

Description

The Identifier class provides a comprehensive naming system for database objects in Paimon. It consists of two main components: a database name and an object name. The object name can be a simple table name or include additional qualifiers for branches and system tables using the "$" separator.

Identifier supports Paimon's branching feature, allowing tables to have multiple named branches (with "main" as the default). System tables, which provide metadata and internal views of user tables, are also represented through identifiers with special suffixes. The class handles the parsing and construction of these complex names transparently.

The implementation is JSON-serializable using Jackson annotations, making it suitable for storage and transmission in distributed systems. It provides multiple factory methods for construction and includes support for escaped names to handle special characters in SQL contexts. The class also defines a standard schema representation for use in data processing operations.

Usage

Use Identifier whenever you need to reference a table, view, or other catalog object in Paimon. It's essential for catalog operations like creating, dropping, or querying tables. The identifier handles the complexity of branch-aware and system table naming, providing a clean API for both simple and complex object references.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-api/src/main/java/org/apache/paimon/catalog/Identifier.java

Signature

@Public
@JsonIgnoreProperties(ignoreUnknown = true)
public class Identifier implements Serializable {
    public static final String SYSTEM_TABLE_SPLITTER = "$";
    public static final String SYSTEM_BRANCH_PREFIX = "branch_";
    public static final String DEFAULT_MAIN_BRANCH = "main";
    public static final String UNKNOWN_DATABASE = "unknown";

    @JsonCreator
    public Identifier(@JsonProperty("database") String database, @JsonProperty("object") String object)
    public Identifier(String database, String table, @Nullable String branch)
    public Identifier(String database, String table, @Nullable String branch, @Nullable String systemTable)

    @JsonGetter("database") public String getDatabaseName()
    @JsonGetter("object") public String getObjectName()
    @JsonIgnore public String getFullName()
    @JsonIgnore public String getTableName()
    @JsonIgnore public @Nullable String getBranchName()
    @JsonIgnore public String getBranchNameOrDefault()
    @JsonIgnore public @Nullable String getSystemTableName()
    @JsonIgnore public boolean isSystemTable()
    @JsonIgnore public String getEscapedFullName()
    @JsonIgnore public String getEscapedFullName(char escapeChar)

    public static Identifier create(String db, String object)
    public static Identifier fromString(String fullName)
}

Import

import org.apache.paimon.catalog.Identifier;

I/O Contract

Inputs

Name	Type	Required	Description
database	String	Yes	Database name
object	String	Yes	Object name (may include branch and system table qualifiers)
table	String	Yes	Base table name (when constructing with separate components)
branch	String	No	Branch name (null for main branch)
systemTable	String	No	System table suffix (null for regular tables)
fullName	String	Yes	Fully qualified name in "database.object" format (for fromString)

Outputs

Name	Type	Description
databaseName	String	The database component
objectName	String	The full object name including qualifiers
fullName	String	Qualified name as "database.object"
tableName	String	The base table name without qualifiers
branchName	String	The branch name, or null for main branch
branchNameOrDefault	String	The branch name, or "main" if null
systemTableName	String	The system table suffix, or null for regular tables
escapedFullName	String	Fully qualified name with backtick escaping

Usage Examples

// Simple table identifier
Identifier id1 = Identifier.create("my_db", "my_table");
System.out.println(id1.getFullName()); // "my_db.my_table"

// Table with branch
Identifier id2 = new Identifier("my_db", "my_table", "feature_branch");
System.out.println(id2.getObjectName()); // "my_table$branch_feature_branch"
System.out.println(id2.getBranchName()); // "feature_branch"

// System table identifier
Identifier id3 = new Identifier("my_db", "my_table", null, "snapshots");
System.out.println(id3.getObjectName()); // "my_table$snapshots"
System.out.println(id3.isSystemTable()); // true

// Branch and system table together
Identifier id4 = new Identifier("my_db", "my_table", "dev", "files");
System.out.println(id4.getObjectName()); // "my_table$branch_dev$files"

// Parsing from string
Identifier id5 = Identifier.fromString("warehouse.orders");
System.out.println(id5.getDatabaseName()); // "warehouse"
System.out.println(id5.getTableName()); // "orders"

// Using in SQL generation
Identifier tableId = Identifier.create("db", "my_table");
String sql = "SELECT * FROM " + tableId.getEscapedFullName();
// "SELECT * FROM `db`.`my_table`"

// Catalog operations
catalog.createTable(identifier, schema, false);
Table table = catalog.getTable(identifier);
catalog.dropTable(identifier, false);

Related Pages

• Principle:Apache_Paimon_Catalog_Object_Model