Class IcebergRestCatalog

Client for interacting with an Apache Iceberg REST Catalog.

This class provides methods for managing namespaces and tables in an Iceberg catalog. It handles authentication, request formatting, and error handling automatically.

Example

const catalog = new IcebergRestCatalog({
  baseUrl: 'https://my-catalog.example.com/iceberg/v1',
  auth: { type: 'bearer', token: process.env.ICEBERG_TOKEN }
});

// Create a namespace
await catalog.createNamespace({ namespace: ['analytics'] });

// Create a table
await catalog.createTable(
  { namespace: ['analytics'] },
  {
    name: 'events',
    schema: { type: 'struct', fields: [...] }
  }
);

Index

Constructors

constructor

Methods

createNamespace createNamespaceIfNotExists createTable createTableIfNotExists dropNamespace dropTable listNamespaces listTables loadNamespaceMetadata loadTable namespaceExists tableExists updateTable

Constructors

constructor

new IcebergRestCatalog(options: IcebergRestCatalogOptions): IcebergRestCatalog
Creates a new Iceberg REST Catalog client.
Parameters
- options: IcebergRestCatalogOptions
  Configuration options for the catalog client
Returns IcebergRestCatalog
- Defined in src/catalog/IcebergRestCatalog.ts:83

Methods

createNamespace

createNamespace(
id: NamespaceIdentifier,
metadata?: NamespaceMetadata,
): Promise<void>
Creates a new namespace in the catalog.
Parameters
- id: NamespaceIdentifier
  Namespace identifier to create
- Optionalmetadata: NamespaceMetadata
  Optional metadata properties for the namespace
Returns Promise<void>
Example
```
await catalog.createNamespace(
  { namespace: ['analytics'] },
  { properties: { owner: 'data-team' } }
);
```
- Defined in src/catalog/IcebergRestCatalog.ts:137

createNamespaceIfNotExists

createNamespaceIfNotExists(
id: NamespaceIdentifier,
metadata?: NamespaceMetadata,
): Promise<void>
Creates a namespace if it does not exist.

If the namespace already exists, does nothing.
Parameters
- id: NamespaceIdentifier
  Namespace identifier to create
- Optionalmetadata: NamespaceMetadata
  Optional metadata properties for the namespace
Returns Promise<void>
Example
```
await catalog.createNamespaceIfNotExists(
  { namespace: ['analytics'] },
  { properties: { owner: 'data-team' } }
);
```
- Defined in src/catalog/IcebergRestCatalog.ts:329

createTable

createTable(
namespace: NamespaceIdentifier,
request: CreateTableRequest,
): Promise<TableMetadata>

Creates a new table in the catalog.

Parameters

namespace: NamespaceIdentifier
Namespace to create the table in
request: CreateTableRequest
Table creation request including name, schema, partition spec, etc.

Returns Promise<TableMetadata>

Table metadata for the created table

Example

const metadata = await catalog.createTable(
  { namespace: ['analytics'] },
  {
    name: 'events',
    schema: {
      type: 'struct',
      fields: [
        { id: 1, name: 'id', type: 'long', required: true },
        { id: 2, name: 'timestamp', type: 'timestamp', required: true }
      ],
      'schema-id': 0
    },
    'partition-spec': {
      'spec-id': 0,
      fields: [
        { source_id: 2, field_id: 1000, name: 'ts_day', transform: 'day' }
      ]
    }
  }
);

createTableIfNotExists

createTableIfNotExists(
namespace: NamespaceIdentifier,
request: CreateTableRequest,
): Promise<TableMetadata>
Creates a table if it does not exist.

If the table already exists, returns its metadata instead.
Parameters
- namespace: NamespaceIdentifier
  Namespace to create the table in
- request: CreateTableRequest
  Table creation request including name, schema, partition spec, etc.
Returns Promise<TableMetadata>
Table metadata for the created or existing table
Example
```
const metadata = await catalog.createTableIfNotExists(
  { namespace: ['analytics'] },
  {
    name: 'events',
    schema: {
      type: 'struct',
      fields: [
        { id: 1, name: 'id', type: 'long', required: true },
        { id: 2, name: 'timestamp', type: 'timestamp', required: true }
      ],
      'schema-id': 0
    }
  }
);
```
- Defined in src/catalog/IcebergRestCatalog.ts:363

dropNamespace

dropNamespace(id: NamespaceIdentifier): Promise<void>
Drops a namespace from the catalog.

The namespace must be empty (contain no tables) before it can be dropped.
Parameters
- id: NamespaceIdentifier
  Namespace identifier to drop
Returns Promise<void>
Example
```
await catalog.dropNamespace({ namespace: ['analytics'] });
```
- Defined in src/catalog/IcebergRestCatalog.ts:153

dropTable

dropTable(id: TableIdentifier, options?: DropTableRequest): Promise<void>
Drops a table from the catalog.
Parameters
- id: TableIdentifier
  Table identifier to drop
- Optionaloptions: DropTableRequest
Returns Promise<void>
Example
```
await catalog.dropTable({ namespace: ['analytics'], name: 'events' });
```
- Defined in src/catalog/IcebergRestCatalog.ts:260

listNamespaces

listNamespaces(parent?: NamespaceIdentifier): Promise<NamespaceIdentifier[]>
Lists all namespaces in the catalog.
Parameters
- Optionalparent: NamespaceIdentifier
  Optional parent namespace to list children under
Returns Promise<NamespaceIdentifier[]>
Array of namespace identifiers
Example
```
// List all top-level namespaces
const namespaces = await catalog.listNamespaces();

// List namespaces under a parent
const children = await catalog.listNamespaces({ namespace: ['analytics'] });
```
- Defined in src/catalog/IcebergRestCatalog.ts:119

listTables

listTables(namespace: NamespaceIdentifier): Promise<TableIdentifier[]>
Lists all tables in a namespace.
Parameters
- namespace: NamespaceIdentifier
  Namespace identifier to list tables from
Returns Promise<TableIdentifier[]>
Array of table identifiers
Example
```
const tables = await catalog.listTables({ namespace: ['analytics'] });
console.log(tables); // [{ namespace: ['analytics'], name: 'events' }, ...]
```
- Defined in src/catalog/IcebergRestCatalog.ts:185

loadNamespaceMetadata

loadNamespaceMetadata(id: NamespaceIdentifier): Promise<NamespaceMetadata>
Loads metadata for a namespace.
Parameters
- id: NamespaceIdentifier
  Namespace identifier to load
Returns Promise<NamespaceMetadata>
Namespace metadata including properties
Example
```
const metadata = await catalog.loadNamespaceMetadata({ namespace: ['analytics'] });
console.log(metadata.properties);
```
- Defined in src/catalog/IcebergRestCatalog.ts:169

loadTable

loadTable(id: TableIdentifier): Promise<TableMetadata>
Loads metadata for a table.
Parameters
- id: TableIdentifier
  Table identifier to load
Returns Promise<TableMetadata>
Table metadata including schema, partition spec, location, etc.
Example
```
const metadata = await catalog.loadTable({ namespace: ['analytics'], name: 'events' });
console.log(metadata.schema);
console.log(metadata.location);
```
- Defined in src/catalog/IcebergRestCatalog.ts:277

namespaceExists

namespaceExists(id: NamespaceIdentifier): Promise<boolean>
Checks if a namespace exists in the catalog.
Parameters
- id: NamespaceIdentifier
  Namespace identifier to check
Returns Promise<boolean>
True if the namespace exists, false otherwise
Example
```
const exists = await catalog.namespaceExists({ namespace: ['analytics'] });
console.log(exists); // true or false
```
- Defined in src/catalog/IcebergRestCatalog.ts:293

tableExists

tableExists(id: TableIdentifier): Promise<boolean>
Checks if a table exists in the catalog.
Parameters
- id: TableIdentifier
  Table identifier to check
Returns Promise<boolean>
True if the table exists, false otherwise
Example
```
const exists = await catalog.tableExists({ namespace: ['analytics'], name: 'events' });
console.log(exists); // true or false
```
- Defined in src/catalog/IcebergRestCatalog.ts:309

updateTable

updateTable(
id: TableIdentifier,
request: UpdateTableRequest,
): Promise<TableMetadata>
Updates an existing table's metadata.

Can update the schema, partition spec, or properties of a table.
Parameters
- id: TableIdentifier
  Table identifier to update
- request: UpdateTableRequest
  Update request with fields to modify
Returns Promise<TableMetadata>
Updated table metadata
Example
```
const updated = await catalog.updateTable(
  { namespace: ['analytics'], name: 'events' },
  {
    properties: { 'read.split.target-size': '134217728' }
  }
);
```
- Defined in src/catalog/IcebergRestCatalog.ts:246

Class IcebergRestCatalog

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns IcebergRestCatalog

Methods

createNamespace

Parameters

Returns Promise<void>

Example

createNamespaceIfNotExists

Parameters

Returns Promise<void>

Example

createTable

Parameters

Returns Promise<TableMetadata>

Example

createTableIfNotExists

Parameters

Returns Promise<TableMetadata>

Example

dropNamespace

Parameters

Returns Promise<void>

Example

dropTable

Parameters

Returns Promise<void>

Example

listNamespaces

Parameters

Returns Promise<NamespaceIdentifier[]>

Example

listTables

Parameters

Returns Promise<TableIdentifier[]>

Example

loadNamespaceMetadata

Parameters

Returns Promise<NamespaceMetadata>

Example

loadTable

Parameters

Returns Promise<TableMetadata>

Example

namespaceExists

Parameters

Returns Promise<boolean>

Example

tableExists

Parameters

Returns Promise<boolean>

Example

updateTable

Parameters

Returns Promise<TableMetadata>

Example

Settings

On This Page