Catalogs - oleander

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.

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

include_tables

bool

default:"False"

Also walk every catalog and populate catalogs with visible tables. Keyword-only.

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.

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.

# 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

catalog

str

default:"oleander"

Catalog to list tables from.

namespace

Optional[str]

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

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.

metadata = await client.get_catalog_table_metadata("flowers")
print(metadata.table["location"], metadata.table.get("current-snapshot-id"))

Parameters

table

str

required

Table name.

catalog

str

default:"oleander"

Catalog name. Keyword-only.

namespace

str

default:"default"

Namespace name. Keyword-only.

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

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`

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

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

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:

snapshot_id

Optional[str]

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

partition_filters

Optional[list[PartitionFilter | dict]]

Restrict the size computation to matching partitions. Each filter has key and value; plain dicts are accepted. Keyword-only.

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

​list_catalogs(*, include_tables=False)

​Parameters

​Return type: ListCatalogsResult

​list_catalog_namespaces(catalog="oleander")

​Return type: ListCatalogNamespacesResult

​list_catalog_tables(catalog="oleander", namespace=None)

​Parameters

​Return type: ListCatalogTablesResult

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

​Parameters

​Return type: CatalogTableMetadata

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

​Return type: CatalogTableSchema

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

​Parameters

​Return type: CatalogTableSize

`list_catalogs(*, include_tables=False)`

Parameters

Return type: `ListCatalogsResult`

`list_catalog_namespaces(catalog="oleander")`

Return type: `ListCatalogNamespacesResult`

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

Parameters

Return type: `ListCatalogTablesResult`

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

Parameters

Return type: `CatalogTableMetadata`

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

Return type: `CatalogTableSchema`

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

Parameters

Return type: `CatalogTableSize`