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

## `list_catalogs(*, include_tables=False)`

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

```python theme={null}
result = await client.list_catalogs()
for catalog in result.registered_catalogs:
    print(catalog.name, catalog.type)

# Also enumerate every visible table (slower)
result = await client.list_catalogs(include_tables=True)
for ref in result.catalogs:
    print(f"{ref.catalog}.{ref.namespace}.{ref.table}")
```

### Parameters

<ParamField body="include_tables" type="bool" default="False">
  Also walk every catalog and populate `catalogs` with visible tables. Keyword-only.
</ParamField>

### Return type: `ListCatalogsResult`

| Field                 | Type                      | Description                                                                                                           |
| --------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `ok`                  | `bool`                    | Whether the request succeeded                                                                                         |
| `catalogs`            | `list[CatalogTableRef]`   | `catalog`/`namespace`/`table` triples; populated only with `include_tables`                                           |
| `registered_catalogs` | `list[RegisteredCatalog]` | Registered catalogs with `name`, `type`, `properties`, and optionally `id`, `created_at`, `updated_at`, `table_count` |

***

## `list_catalog_namespaces(catalog="oleander")`

List Iceberg namespaces in a catalog.

```python theme={null}
result = await client.list_catalog_namespaces()
print(result.namespaces)

# or for a registered external catalog:
external = await client.list_catalog_namespaces("my-glue-catalog")
```

### Return type: `ListCatalogNamespacesResult`

| Field        | Type        | Description                   |
| ------------ | ----------- | ----------------------------- |
| `ok`         | `bool`      | Whether the request succeeded |
| `catalog`    | `str`       | The catalog that was listed   |
| `namespaces` | `list[str]` | Namespace names               |

***

## `list_catalog_tables(catalog="oleander", namespace=None)`

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.

```python theme={null}
# All tables across all namespaces of the default catalog
result = await client.list_catalog_tables()

# Tables in a single namespace
scoped = await client.list_catalog_tables("oleander", namespace="default")
for ref in scoped.tables:
    print(f"{ref.catalog}.{ref.namespace}.{ref.table}")
```

### Parameters

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

<ParamField body="namespace" type="Optional[str]">
  Restrict listing to one namespace. Omit to list across all namespaces.
</ParamField>

### Return type: `ListCatalogTablesResult`

| Field    | Type                    | Description                           |
| -------- | ----------------------- | ------------------------------------- |
| `ok`     | `bool`                  | Whether the request succeeded         |
| `tables` | `list[CatalogTableRef]` | `catalog`/`namespace`/`table` triples |

***

## `get_catalog_table_metadata(table, *, catalog="oleander", namespace="default")`

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.

```python theme={null}
metadata = await client.get_catalog_table_metadata("flowers")
print(metadata.table["location"], metadata.table.get("current-snapshot-id"))
```

### Parameters

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

<ParamField body="catalog" type="str" default="oleander">
  Catalog name. Keyword-only.
</ParamField>

<ParamField body="namespace" type="str" default="default">
  Namespace name. Keyword-only.
</ParamField>

### Return type: `CatalogTableMetadata`

| Field   | Type             | Description                   |
| ------- | ---------------- | ----------------------------- |
| `ok`    | `bool`           | Whether the request succeeded |
| `table` | `dict[str, Any]` | Raw Iceberg table metadata    |

***

## `get_catalog_table_schema(table, *, catalog="oleander", namespace="default")`

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 `get_catalog_table_metadata()` for the full metadata including schema history.

Accepts the same parameters as `get_catalog_table_metadata()`.

```python theme={null}
schema = await client.get_catalog_table_schema("flowers")
for field in schema.fields:
    print(field.name, field.type, field.required)
```

### Return type: `CatalogTableSchema`

| Field       | Type                       | Description                                                      |
| ----------- | -------------------------- | ---------------------------------------------------------------- |
| `catalog`   | `str`                      | Catalog name                                                     |
| `namespace` | `str`                      | Namespace name                                                   |
| `table`     | `str`                      | Table name                                                       |
| `schema_id` | `Optional[int]`            | The resolved schema ID                                           |
| `fields`    | `list[IcebergSchemaField]` | Fields with `id`, `name`, `type`, `required`, and optional `doc` |

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

***

## `get_catalog_table_size(table, *, catalog="oleander", namespace="default", snapshot_id=None, partition_filters=None)`

Compute the size of a table or a partition subset. `size_bytes` and `record_count` are returned as strings since they can exceed 2^53.

```python theme={null}
size = await client.get_catalog_table_size("events")
print(size.size_bytes, size.record_count, size.data_file_count)

# Size of one partition at a specific snapshot
from oleander_sdk import PartitionFilter

partition = await client.get_catalog_table_size(
    "events",
    snapshot_id="1234567890123456789",
    partition_filters=[PartitionFilter(key="day", value="2026-07-01")],
)
```

### Parameters

Accepts the same `table`/`catalog`/`namespace` parameters as `get_catalog_table_metadata()`, plus:

<ParamField body="snapshot_id" type="Optional[str]">
  Compute the size at a specific snapshot instead of the current one. Keyword-only.
</ParamField>

<ParamField body="partition_filters" type="Optional[list[PartitionFilter | dict]]">
  Restrict the size computation to matching partitions. Each filter has `key` and `value`; plain dicts are accepted. Keyword-only.
</ParamField>

### Return type: `CatalogTableSize`

| Field               | Type                    | Description                                   |
| ------------------- | ----------------------- | --------------------------------------------- |
| `ok`                | `bool`                  | Whether the request succeeded                 |
| `catalog`           | `str`                   | Catalog name                                  |
| `namespace`         | `str`                   | Namespace name                                |
| `table`             | `str`                   | Table name                                    |
| `snapshot_id`       | `Optional[str]`         | Snapshot the size was computed at             |
| `size_bytes`        | `str`                   | Total data size in bytes (stringified bigint) |
| `record_count`      | `str`                   | Total record count (stringified bigint)       |
| `data_file_count`   | `int`                   | Number of data files                          |
| `partition_filters` | `list[PartitionFilter]` | Filters applied, if any                       |