Catalogs

Catalog methods let you introspect the Iceberg catalogs registered in oleander. Unless specified otherwise, catalog defaults to the built-in oleander catalog and namespace defaults to default.

`listCatalogs(options?)`

List the Iceberg catalogs registered in oleander. Pass includeTables: true to also walk every catalog and return the visible catalog/namespace/table triples in catalogs — this is slower; otherwise catalogs is empty.

const { registeredCatalogs } = await client.listCatalogs();
for (const catalog of registeredCatalogs) {
  console.log(catalog.name, catalog.type);
}

// Also enumerate every visible table (slower)
const { catalogs } = await client.listCatalogs({ includeTables: true });
for (const ref of catalogs) {
  console.log(`${ref.catalog}.${ref.namespace}.${ref.table}`);
}

Parameters

boolean

default:"false"

Also walk every catalog and populate catalogs with visible tables.

Return type: `ListCatalogsResult`

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`catalogs`	`CatalogTableRef[]`	`{ catalog, namespace, table }` triples; populated only with `includeTables`
`registeredCatalogs`	`RegisteredCatalog[]`	Registered catalogs with `name`, `type`, `properties`, and optionally `id`, `created_at`, `updated_at`, `tableCount`

`listCatalogNamespaces(catalog?)`

List Iceberg namespaces in a catalog.

const { namespaces } = await client.listCatalogNamespaces();
// or for a registered external catalog:
const external = await client.listCatalogNamespaces("my-glue-catalog");

Return type: `ListCatalogNamespacesResult`

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`catalog`	`string`	The catalog that was listed
`namespaces`	`string[]`	Namespace names

`listCatalogTables(options?)`

List Iceberg tables in a catalog. When namespace is omitted, tables are listed across all namespaces in the catalog; namespaces that fail to list are skipped.

// All tables across all namespaces of the default catalog
const { tables } = await client.listCatalogTables();

// Tables in a single namespace
const scoped = await client.listCatalogTables({
  catalog: "oleander",
  namespace: "default",
});
for (const ref of scoped.tables) {
  console.log(`${ref.catalog}.${ref.namespace}.${ref.table}`);
}

Parameters

string

default:"oleander"

Catalog to list tables from.

string

Restrict listing to one namespace. Omit to list across all namespaces.

Return type: `ListCatalogTablesResult`

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`tables`	`CatalogTableRef[]`	`{ catalog, namespace, table }` triples

`getCatalogTableMetadata(options)`

Read the Iceberg REST catalog metadata for a single table. The result’s table field is the raw Iceberg metadata: location, schemas, partition-specs, snapshots, properties, and so on.

const { table } = await client.getCatalogTableMetadata({ table: "flowers" });
console.log(table.location, table["current-snapshot-id"]);

Parameters

string

required

Table name.

string

default:"oleander"

Catalog name.

string

default:"default"

Namespace name.

Return type: `CatalogTableMetadataResult`

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`table`	`Record<string, unknown>`	Raw Iceberg table metadata

`getCatalogTableSchema(options)`

Get the current schema of a table as a flat field list. Resolves current-schema-id against the schemas array of the Iceberg metadata, falling back to the newest schema. Use getCatalogTableMetadata() for the full metadata including schema history. Accepts the same options as getCatalogTableMetadata().

const schema = await client.getCatalogTableSchema({ table: "flowers" });
for (const field of schema.fields) {
  console.log(field.name, field.type, field.required);
}

Return type: `CatalogTableSchemaResult`

Field	Type	Description
`catalog`	`string`	Catalog name
`namespace`	`string`	Namespace name
`table`	`string`	Table name
`schemaId`	nullable number	The resolved schema ID
`fields`	`IcebergSchemaField[]`	Fields with `id`, `name`, `type`, `required`, and optional `doc`

type is a string for primitive types (for example, "long" or "string") and an object for nested types such as struct, list, and map.

`getCatalogTableSize(options)`

Compute the size of a table or a partition subset. sizeBytes and recordCount are returned as strings since they can exceed Number.MAX_SAFE_INTEGER.

const size = await client.getCatalogTableSize({ table: "events" });
console.log(size.sizeBytes, size.recordCount, size.dataFileCount);

// Size of one partition at a specific snapshot
const partition = await client.getCatalogTableSize({
  table: "events",
  snapshotId: "1234567890123456789",
  partitionFilters: [{ key: "day", value: "2026-07-01" }],
});

Parameters

Accepts the same table/catalog/namespace options as getCatalogTableMetadata(), plus:

string

Compute the size at a specific snapshot instead of the current one.

{ key, value }[]

default:"[]"

Restrict the size computation to matching partitions.

Return type: `CatalogTableSizeResult`

Field	Type	Description
`ok`	`boolean`	Whether the request succeeded
`catalog`	`string`	Catalog name
`namespace`	`string`	Namespace name
`table`	`string`	Table name
`snapshotId`	nullable string	Snapshot the size was computed at
`sizeBytes`	`string`	Total data size in bytes (stringified bigint)
`recordCount`	`string`	Total record count (stringified bigint)
`dataFileCount`	`number`	Number of data files
`partitionFilters`	`{ key, value }[]`	Filters applied, if any

TypeScript

Python

`listCatalogs(options?)`

Parameters

Return type: `ListCatalogsResult`

`listCatalogNamespaces(catalog?)`

Return type: `ListCatalogNamespacesResult`

`listCatalogTables(options?)`

Parameters

Return type: `ListCatalogTablesResult`

`getCatalogTableMetadata(options)`

Parameters

Return type: `CatalogTableMetadataResult`

`getCatalogTableSchema(options)`

Return type: `CatalogTableSchemaResult`

`getCatalogTableSize(options)`

Parameters

Return type: `CatalogTableSizeResult`

​listCatalogs(options?)

​Parameters

​Return type: ListCatalogsResult

​listCatalogNamespaces(catalog?)

​Return type: ListCatalogNamespacesResult

​listCatalogTables(options?)

​Parameters

​Return type: ListCatalogTablesResult

​getCatalogTableMetadata(options)

​Parameters

​Return type: CatalogTableMetadataResult

​getCatalogTableSchema(options)

​Return type: CatalogTableSchemaResult

​getCatalogTableSize(options)

​Parameters

​Return type: CatalogTableSizeResult

`listCatalogs(options?)`

Parameters

Return type: `ListCatalogsResult`

`listCatalogNamespaces(catalog?)`

Return type: `ListCatalogNamespacesResult`

`listCatalogTables(options?)`

Parameters

Return type: `ListCatalogTablesResult`

`getCatalogTableMetadata(options)`

Parameters

Return type: `CatalogTableMetadataResult`

`getCatalogTableSchema(options)`

Return type: `CatalogTableSchemaResult`

`getCatalogTableSize(options)`

Parameters

Return type: `CatalogTableSizeResult`