nordisk/skade

The Iceberg Catalog surface — guide

Class: guide · Function: catalog. The what is in catalog-design.md.

Namespaces

use iceberg::{Catalog, NamespaceIdent};
use std::collections::HashMap;

let ns = NamespaceIdent::from_strs(["sales"])?;
catalog.create_namespace(&ns, HashMap::from([
    ("location".into(), "file:///wh/sales".into()),
])).await?;

catalog.namespace_exists(&ns).await?;           // -> true
catalog.list_namespaces(None).await?;           // top-level namespaces
catalog.get_namespace(&ns).await?;              // with its properties

Nested namespaces join with . internally; list_namespaces(Some(&parent)) returns only direct children. update_namespace replaces the whole property set (it is not a merge). drop_namespace fails if any table still lives in it — drop or rename the tables first.

Tables

use iceberg::{TableCreation, TableIdent};

// Create — if you omit `location`, it defaults to the namespace `location`
// property, else `<warehouse>/<ns>/<table>`.
let table = catalog.create_table(&ns, TableCreation::builder()
    .name("orders".into())
    .schema(schema)
    .build()).await?;

let ident = TableIdent::new(ns.clone(), "orders".into());
catalog.table_exists(&ident).await?;            // L1 fast path
let t = catalog.load_table(&ident).await?;      // warm: handle-cache clone
catalog.list_tables(&ns).await?;
catalog.rename_table(&ident, &new_ident).await?;
catalog.drop_table(&ident).await?;              // drops the pointer, not the data files

Skade-only reads (skip the Table build)

When you only need metadata — schema, snapshots, properties, current location — use resolve_metadata, which returns an Arc<TableMetadata> without paying for Table::build():

let meta = catalog.resolve_metadata(&ident).await?;   // Arc<TableMetadata>
let schema = meta.current_schema();

Registering an existing table

Adopt a metadata file written elsewhere (e.g. by another tool) under a new identifier:

catalog.register_table(&ident, "file:///wh/sales/orders/metadata/…json".into()).await?;

register_table errors TableAlreadyExists if the identifier is taken. Two identifiers may point at the same metadata file; the handle cache keys on the location but checks the identifier, so it won't hand you the wrong table.