Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us