Browse Iceberg catalogs, namespaces, and tables, and inspect table metadata, schemas, and sizes.
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 catalogconst { tables } = await client.listCatalogTables();// Tables in a single namespaceconst 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.
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 snapshotconst 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.