> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalogs and placement

> Register catalogs, place datasets explicitly, bind external datasets and drain a catalog

In the normal path a dataset's `storage` names its catalog and table, and
deploying it binds the dataset and starts the export; see the
[overview](/datasets/overview#publish-a-table). This page covers the catalog
itself and the cases that need an explicit binding.

## Register a catalog

Provision the catalog, namespace and storage with your provider. Store the
catalog's JSON property map in the deployment's private credential inventory and
register it once per deployment:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection integration credential-create ANALYTICS_CATALOG --from-file catalog-properties.json
bijection dataset catalog register analytics --credential-ref ANALYTICS_CATALOG
bijection dataset catalog status
```

Keep `catalog-properties.json` private and out of source control; declarations
and binding files contain only the credential reference.
`bijection dataset catalog status analytics` shows the catalog's setup, its
placements and any outstanding work; add `--watch` to follow it. Bijection
creates missing tables and validates existing ones against your deployed
declarations. It never creates namespaces or drops tables.

## Bind a dataset explicitly

Bind explicitly when a dataset declares no `storage`, when you choose its table
at deploy time, or for an [external dataset](/datasets/customer-compute#declare-the-result)
that a job writes:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection dataset bind orders --catalog analytics --table app.orders --check
bijection dataset bind orders --catalog analytics --table app.orders --wait 2m
```

`--check` contacts the catalog and reports the access the binding needs, without
submitting it. It creates no tables and does not test storage writes; submission
checks the catalog again. `--wait` observes the accepted binding until every
selected dataset has a published version, for at most the given duration;
publication continues after the command exits. A dataset that declares
`storage` binds as declared with `bijection dataset bind orders`; a binding that
differs from the declaration is refused. A keyed external dataset also needs
`--buckets`, its fixed logical bucket count from 1 to 32.

To bind many datasets at once, put them in a file:

```json binding.json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "catalog": { "identity": "analytics", "credentialRef": "ANALYTICS_CATALOG" },
  "datasets": {
    "orders": {
      "catalog": "analytics",
      "table": ["app", "orders"],
      "retention": "managed"
    }
  }
}
```

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection dataset bind --config binding.json --check
bijection dataset bind --config binding.json --wait 2m
```

Repeat an interrupted bind with the same configuration. To require a particular
existing table, add its `tableUuid` to the binding.

## Follow publication

`bijection dataset status` is the entry point for every dataset:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection dataset status
bijection dataset status orders --watch
bijection dataset status orders --format json
bijection dataset status orders --binding-revision 2 --wait 2m
```

Without a dataset it lists every declared dataset with its target, serving
state and publication summary. `--watch` refreshes once a second until
interrupted; `--format jsonl` emits one observation per line. With
`--binding-revision` or `--after <receipt>`, it waits for that exact
requirement for at most `--wait`.

Unknown freshness means there is no source observation yet; a successful check
does not establish freshness. A publisher can be offline while its last complete
version remains readable. Attention distinguishes automatic recovery from an
action you must take. Each observation still checks current access.

`bijection dataset pause orders` and `resume` stop and restart publication
without changing the binding. `bijection dataset resnapshot orders --request-id <key>` establishes a new source basis when the source history can no longer be
continued.

## Drain a catalog

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bijection dataset catalog drain analytics --wait 2m
```

Draining stops publication to the catalog and waits for recorded work to settle;
retained checkpoints must be released first. It preserves customer tables,
catalogs and infrastructure. Each drained table keeps the property
`bijection.publication-state` set to `stopped` and
`bijection.publication-stopped-boundary` set to the last complete source
position it reflects. Binding a table again removes both. To move a dataset to
another table, drain its catalog, then bind it again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.