> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleander.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalogs

> 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.

```ts theme={null}
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

<ParamField body="options.includeTables" type="boolean" default="false">
  Also walk every catalog and populate `catalogs` with visible tables.
</ParamField>

### 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.

```ts theme={null}
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.

```ts theme={null}
// 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

<ParamField body="options.catalog" type="string" default="oleander">
  Catalog to list tables from.
</ParamField>

<ParamField body="options.namespace" type="string">
  Restrict listing to one namespace. Omit to list across all namespaces.
</ParamField>

### 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.

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

### Parameters

<ParamField body="options.table" type="string" required>
  Table name.
</ParamField>

<ParamField body="options.catalog" type="string" default="oleander">
  Catalog name.
</ParamField>

<ParamField body="options.namespace" type="string" default="default">
  Namespace name.
</ParamField>

### 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()`.

```ts theme={null}
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` |

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

***

## `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`.

```ts theme={null}
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:

<ParamField body="options.snapshotId" type="string">
  Compute the size at a specific snapshot instead of the current one.
</ParamField>

<ParamField body="options.partitionFilters" type="{ key, value }[]" default="[]">
  Restrict the size computation to matching partitions.
</ParamField>

### 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.