Namespace

Namespace representation in Apache Iceberg catalogs

A Namespace represents a hierarchical namespace in an Iceberg catalog, similar to a database or schema in traditional database systems.

Overview

Namespaces provide a way to organize tables hierarchically. A namespace can have multiple levels, such as warehouse.department.team.

Class

public class Namespace

Creating Namespaces

of()

Creates a namespace from the given levels.

public static Namespace of(String... levels)

Parameters:

• levels - The namespace levels

Returns: A new Namespace instance

Example:

// Single level namespace
Namespace db = Namespace.of("my_database");

// Multi-level namespace
Namespace nested = Namespace.of("warehouse", "analytics", "production");

empty()

Returns an empty namespace.

public static Namespace empty()

Returns: An empty namespace instance

Example:

Namespace empty = Namespace.empty();

Instance Methods

levels()

Returns the array of levels in this namespace.

public String[] levels()

Returns: Array of namespace levels

Example:

Namespace ns = Namespace.of("warehouse", "sales");
String[] levels = ns.levels(); // ["warehouse", "sales"]

level()

Returns the level at the specified position.

public String level(int pos)

Parameters:

• pos - The position of the level (0-based)

Returns: The level at the specified position

Example:

Namespace ns = Namespace.of("warehouse", "sales");
String first = ns.level(0);  // "warehouse"
String second = ns.level(1); // "sales"

isEmpty()

Checks if this namespace is empty.

public boolean isEmpty()

Returns: true if the namespace has no levels, false otherwise

Example:

Namespace empty = Namespace.empty();
boolean isEmpty = empty.isEmpty(); // true

Namespace ns = Namespace.of("db");
boolean isDbEmpty = ns.isEmpty(); // false

length()

Returns the number of levels in this namespace.

public int length()

Returns: The number of levels

Example:

Namespace ns = Namespace.of("warehouse", "sales", "2024");
int len = ns.length(); // 3

toString()

Returns a string representation of the namespace with levels separated by dots.

@Override
public String toString()

Returns: String representation of the namespace

Example:

Namespace ns = Namespace.of("warehouse", "sales");
String str = ns.toString(); // "warehouse.sales"

Examples

Creating and Using Namespaces

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

// Create a simple namespace
Namespace db = Namespace.of("analytics");

// Create a multi-level namespace
Namespace nestedNs = Namespace.of("data_warehouse", "sales", "quarterly");

// Use with catalog
Catalog catalog = ...;
List<TableIdentifier> tables = catalog.listTables(db);

// Check namespace properties
if (!db.isEmpty()) {
    System.out.println("Namespace: " + db.toString());
    System.out.println("Levels: " + db.length());
}

Iterating Through Namespace Levels

Namespace ns = Namespace.of("warehouse", "department", "team");

for (int i = 0; i < ns.length(); i++) {
    System.out.println("Level " + i + ": " + ns.level(i));
}
// Output:
// Level 0: warehouse
// Level 1: department
// Level 2: team

Working with Empty Namespaces

Namespace empty = Namespace.empty();

if (empty.isEmpty()) {
    System.out.println("This is an empty namespace");
}

// Empty namespace has no levels
assert empty.length() == 0;
assert empty.toString().equals("");

Validation

Namespaces enforce the following constraints:

• Cannot be created from a null array
• Individual levels cannot be null
• Levels cannot contain the null-byte character (\u0000)

// These will throw exceptions:

// Namespace.of(null); // IllegalArgumentException
// Namespace.of("db", null, "table"); // IllegalArgumentException

See Also

• Catalog - Catalog API for namespace and table operations
• TableIdentifier - Table identification with namespaces
• SupportsNamespaces - Catalog extension for namespace operations