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