Skip to main content
A TableIdentifier uniquely identifies a table within an Iceberg catalog by combining a namespace and table name.

​
Overview

TableIdentifier provides a standard way to reference tables across different catalog implementations. It consists of a namespace (which may be empty) and a table name.

​
Class

public class TableIdentifier

​
Creating Table Identifiers

​
of() with String Array

Creates a table identifier from an array of names. The last element is the table name, and preceding elements form the namespace. 
public static TableIdentifier of(String... names)
Parameters:
  • names - Array where the last element is the table name and preceding elements are namespace levels
Returns: A new TableIdentifier instance Example: 
// Table "users" in namespace "db"
TableIdentifier id1 = TableIdentifier.of("db", "users");

// Table "events" in multi-level namespace
TableIdentifier id2 = TableIdentifier.of("warehouse", "analytics", "events");

// Table with no namespace
TableIdentifier id3 = TableIdentifier.of("simple_table");

​
of() with Namespace

Creates a table identifier from a namespace and table name. 
public static TableIdentifier of(Namespace namespace, String name)
Parameters:
  • namespace - A namespace
  • name - The table name
Returns: A new TableIdentifier instance Example: 
Namespace ns = Namespace.of("data_warehouse", "sales");
TableIdentifier id = TableIdentifier.of(ns, "transactions");

​
parse()

Parses a table identifier from a dot-separated string. 
public static TableIdentifier parse(String identifier)
Parameters:
  • identifier - A dot-separated identifier string
Returns: A new TableIdentifier instance Example: 
// Parse "db.schema.table" into identifier
TableIdentifier id = TableIdentifier.parse("analytics.production.events");

// Parse simple table name
TableIdentifier simple = TableIdentifier.parse("users");

​
Instance Methods

​
namespace()

Returns the identifier’s namespace. 
public Namespace namespace()
Returns: The namespace Example: 
TableIdentifier id = TableIdentifier.of("warehouse", "sales", "orders");
Namespace ns = id.namespace(); // Namespace.of("warehouse", "sales")

​
name()

Returns the table name. 
public String name()
Returns: The table name Example: 
TableIdentifier id = TableIdentifier.of("db", "users");
String name = id.name(); // "users"

​
hasNamespace()

Checks whether the namespace is not empty. 
public boolean hasNamespace()
Returns: true if the namespace is not empty, false otherwise Example: 
TableIdentifier id1 = TableIdentifier.of("db", "table");
boolean has1 = id1.hasNamespace(); // true

TableIdentifier id2 = TableIdentifier.of("table");
boolean has2 = id2.hasNamespace(); // false

​
toLowerCase()

Returns a new identifier with all levels converted to lowercase. 
public TableIdentifier toLowerCase()
Returns: A new TableIdentifier with lowercase namespace and name Example: 
TableIdentifier id = TableIdentifier.of("DB", "MyTable");
TableIdentifier lower = id.toLowerCase();
// lower is equivalent to TableIdentifier.of("db", "mytable")

​
toString()

Returns a string representation of the identifier. 
@Override
public String toString()
Returns: Dot-separated string representation Example: 
TableIdentifier id = TableIdentifier.of("warehouse", "sales", "orders");
String str = id.toString(); // "warehouse.sales.orders"

TableIdentifier simple = TableIdentifier.of("users");
String simpleStr = simple.toString(); // "users"

​
Examples

​
Basic Usage with Catalog

import org.apache.iceberg.catalog.TableIdentifier;
import org.apache.iceberg.catalog.Namespace;
import org.apache.iceberg.catalog.Catalog;
import org.apache.iceberg.Table;

// Create identifier and load table
TableIdentifier id = TableIdentifier.of("analytics", "events");
Catalog catalog = ...;
Table table = catalog.loadTable(id);

// Create table with identifier
Schema schema = new Schema(...);
Table newTable = catalog.createTable(id, schema);

​
Working with Multi-Level Namespaces

// Create identifier with multi-level namespace
TableIdentifier id = TableIdentifier.of(
    "data_warehouse",
    "sales",
    "quarterly",
    "q1_transactions"
);

// Access parts
Namespace ns = id.namespace(); // ["data_warehouse", "sales", "quarterly"]
String tableName = id.name();   // "q1_transactions"
String full = id.toString();    // "data_warehouse.sales.quarterly.q1_transactions"

​
Parsing Identifiers

// Parse from configuration or user input
String userInput = "warehouse.production.events";
TableIdentifier id = TableIdentifier.parse(userInput);

if (id.hasNamespace()) {
    System.out.println("Namespace: " + id.namespace());
}
System.out.println("Table: " + id.name());

​
Case Conversion

// Normalize identifiers for case-insensitive comparisons
TableIdentifier original = TableIdentifier.of("Analytics", "Events");
TableIdentifier normalized = original.toLowerCase();

// Use normalized version for lookups
boolean exists = catalog.tableExists(normalized);

​
Equality and Comparison

TableIdentifier id1 = TableIdentifier.of("db", "table");
TableIdentifier id2 = TableIdentifier.of("db", "table");
TableIdentifier id3 = TableIdentifier.parse("db.table");

// All are equal
assert id1.equals(id2);
assert id1.equals(id3);
assert id1.hashCode() == id2.hashCode();

​
Validation

TableIdentifier enforces the following constraints:
  • Table name cannot be null or empty
  • Namespace cannot be null (but can be empty)
  • Cannot be created from a null array
// These will throw exceptions:

// TableIdentifier.of((String[]) null); // IllegalArgumentException
// TableIdentifier.of(); // IllegalArgumentException (no table name)
// TableIdentifier.of(ns, null); // IllegalArgumentException
// TableIdentifier.of(ns, ""); // IllegalArgumentException

​
See Also

  • Catalog - Catalog API for table operations
  • Namespace - Namespace representation
  • Table - Table API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us