# The Iceberg Catalog surface — guide
> **Class:** `guide` · **Function:** `catalog`. The *what* is in
> [`catalog-design.md`](catalog-design.md).
## Namespaces
```rust
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
```rust
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()`:
```rust
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:
```rust
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.