Skip to content

Import and export definitions

Use the admin definition document for repeatable catalogue changes. It contains reusable semantics, bindings, contracts, services, member series, event feeds, and lookups, but no observations, events, credentials, or source secrets.

Export

  1. Open Operations → Export definitions.
  2. Choose an account you can view.
  3. Download the YAML and keep it under normal source-control review.

The export contains current, non-archived master values in dependency order. It is suitable for review, editing, backup of catalogue definitions, and import into another environment. It is not a database backup.

Import

  1. Open Operations → Import definitions.
  2. Paste the YAML or upload the exported file.
  3. Select Dry run first.
  4. Review every create, update, unchanged, skip, and error row and its findings.
  5. Use Apply to write drafts through the normal validation, version, dependency, and audit path.
  6. Use Apply and publish only when the report is clean and publication is intended.

The document's account must be one you can edit. Import never changes a canonical identity. If an existing draft has changed since export, resolve the version conflict instead of overwriting it.

Legacy ClickHouse intake

Operators migrating pre-QuickLookup catalogue heads use the management command. Always start with a report:

uv run python manage.py import_legacy_catalog --mode report --report-path import-report.json
uv run python manage.py import_legacy_catalog --mode apply

Add --publish only after reviewing all findings. Imported objects with blocking findings remain drafts. The publication worker still has to deliver accepted revisions.

POST /v1/import/series is the compatibility intake for a trusted legacy writer. It creates or updates one draft under the caller's authenticated account and returns the review findings; it does not publish.

Do not use import as an ingestion path. Observations and events use their stored-data endpoints after the definition is delivered.