# Migrate from Sanity

> Import a Sanity dataset into Galerne from the export API, the query API or a file, and export Galerne content as a Sanity dataset: options, mapping and what each direction loses.

The Sanity source reads a whole dataset: documents, drafts, translations and assets. It uses the dataset export API, the query API for public datasets without a token, or a file you exported yourself.

## Import

```bash
# with a token: drafts and private datasets included
galerne import --from sanity --project-id abc123 --dataset production --source-token sk… --dry-run

# a public dataset, no token: published documents only
galerne import --from sanity --project-id abc123 --dataset production

# a file from `sanity dataset export production production.tar.gz`
galerne import --from sanity --file production.tar.gz
```

Options go after `--from` as flags in kebab case (`projectId` is `--project-id`). With the `import_from` tool, they go in `options`. See the [migration overview](/docs/migrate.md) for the shared flags, the report and re-runs.

| Option | What it is |
|---|---|
| `projectId` | Sanity project id. Required without `file` or `data` |
| `dataset` | Dataset name. Required without `file` or `data` |
| `token` | A read token, for drafts and private datasets. On the CLI: `--source-token` |
| `apiVersion` | API version, default `v2021-10-21` |
| `file` | A `.tar.gz` or `.tar` from `sanity dataset export` (documents, images and files), or an `.ndjson` file |
| `data` | The NDJSON content inline (tools) |
| `includeDrafts` | `false` skips drafts. Default: included |
| `languageField` | The field that holds a document's language, default `language` |
| `baseLanguage` | The source language of translation groups. Default: the first in each group |
| `urlFiles` | Copy files that fields only link to by URL (`.mp4`, `.pdf`, images) into Galerne media. Default `true` |

With a token, the source calls the export endpoint `https://<projectId>.api.sanity.io/<apiVersion>/data/export/<dataset>`. Without a token, a refused export falls back to the query API, which returns published documents only. `--since` uses a GROQ filter on `_updatedAt`.

## How content maps

| Sanity | Galerne |
|---|---|
| `_type` | Document type |
| `_id` | Document id, kept |
| `drafts.<id>` | The draft of `<id>`; the published document is its published version |
| Portable Text | Rich text, see below |
| `reference` | `reference`, `_weak` kept |
| `slug` (`{ current }`) | `slug` |
| `image` with hotspot and crop | `image` with `hotspot` and `crop`; extra image fields kept |
| `sanity.imageAsset`, `sanity.fileAsset` | Media, with alt text, title, description as caption and credit line as credits |
| `geopoint`, `color`, `code`, `table` | `geopoint`, `color` (hex), `code`, `table` |
| Arrays of objects | `blocks`, keys kept; images, files and references inside arrays become blocks |
| Field-level translations (`locale…` objects, `internationalizedArray…`) | Localized fields |
| Document internationalization (`translation.metadata`, `__i18n_lang`) | Document-level translations with `_lang` and `_translationOf` |
| A type with one document whose id is the type name | A singleton |

## Portable Text

| Portable Text | Galerne rich text |
|---|---|
| Styles `h1` to `h6`, `blockquote` | Headings, blockquote |
| `listItem` and `level` | Nested bullet and ordered lists |
| Decorators `strong`, `em`, `underline`, `strike-through`, `code` | Bold, italic, underline, strike, code |
| Link annotations | Links, `blank` kept as a new tab |
| Annotations that reference a document | `doc:<id>` links |
| Image blocks, code blocks | Images (`media:<id>`), code blocks |
| Other block objects | Embeds of a block type with the same name, listed in the field's `embeds` |

Galerne does not run GROQ: rewrite your queries with the [query API](/docs/query.md).

## What the import loses

The report lists each of these when it happens.

- Other text styles become paragraphs, with a warning.
- Inline objects inside text, and unknown marks and annotations, are dropped and listed.
- System documents and unpublished release versions (`versions.*`) are skipped: publish the release first.
- Hotspot width and height are dropped; Galerne keeps the hotspot point.
- An array mixing plain values and objects keeps only the objects.
- An asset missing from the archive is reported.

## Export to Sanity

```bash
galerne export --to sanity --out ./sanity-export --dataset production
```

| Option | What it is |
|---|---|
| `dataset` | Dataset name used in the folder, default `production` |

The folder holds `<dataset>/data.ndjson` with `images/` and `files/`, the same as a `<dataset>.tar.gz` for `sanity dataset import`, schema types in `schemaTypes/` (`index.ts`, `locale.ts` and one file per type), and a `README.md`. A published document is written under its id; a newer draft, or an unpublished document, under `drafts.<id>`.

The export loses:

- Hotspots are written with a width and height of 1.
- Tables become plain text cells; code fields need `@sanity/code-input` and tables `@sanity/table` in your studio.
- Images inside rich text that do not point to Galerne media are dropped.
- Horizontal rules become `break` blocks.
