Import an External Export

Import rebuilds documents from one external export and writes them into a collection through the same BYO write core as upsert, so imported documents arrive with their vectors and their lineage intact.

The target can be a collection that has a feature extractor. Import goes through the BYO write core and submits no extraction batch, so the vectors in your export are the vectors that get stored. Nothing re-embeds them on the way in, and bucket and object lineage on the imported rows is preserved.This says nothing about later runs. A trigger or a batch you start afterwards treats these documents like any others.

Three calls. The first two write nothing.

Infer a mapping from a sample

POST /v1/collections/import/infer reads a sample of your export and returns the source fields it found with a suggested source-to-target mapping.

curl -X POST "$MP_API_URL/v1/collections/import/infer" \
  -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $NS" \
  -H "Content-Type: application/json" \
  -d '{ "sample_rows": [ { "id": "a1", "title": "...", "embedding": [0.1, 0.2] } ],
        "sample_size": 100 }'

Returns fields and warnings. It runs on the sample alone, so nothing is written and nothing is reserved.

Validate the finished mapping

POST /v1/collections/import/validate-mapping checks the mapping you settled on. mapping is required.

curl -X POST "$MP_API_URL/v1/collections/import/validate-mapping" \
  -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $NS" \
  -H "Content-Type: application/json" \
  -d '{ "mapping": { "fields": [...], "source_type": "collection" } }'

Returns ok plus errors. It flags four things: a missing root-identity mapping, source and target types that disagree, a vector dimension that does not match a known index, and source fields it does not recognise.

Import

POST /v1/collections/{collection_identifier}/import reconstructs the documents and writes them. mapping is required.

curl -X POST "$MP_API_URL/v1/collections/$COLLECTION_ID/import" \
  -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $NS" \
  -H "Content-Type: application/json" \
  -d '{ "export": { ... }, "mapping": { ... }, "dry_run": true }'

Returns reconstructed, imported, skipped, errors, warnings and dry_run.

Reading the result

Field	Meaning
`reconstructed`	Documents rebuilt from the export.
`imported`	Documents written. Always `0` when `dry_run` is true.
`skipped`	Rows that failed reconstruction.
`errors`	Per-row failures.
`warnings`	Non-fatal notes.

A bad row does not stop the batch. skipped counts rows that failed reconstruction while imported counts the ones that were written, so a partially-bad export gives you both, not an all-or-nothing outcome.Compare reconstructed against imported and skipped rather than checking for an error status. A response with errors in it can still have written most of the batch.

Run the third call with "dry_run": true first. It reconstructs and validates the full export, not a sample, and writes nothing — imported comes back 0 while reconstructed and skipped tell you what the real run would do.Step 2 validates the mapping. A dry run validates the mapping against every row of the actual export, which is a different and stronger check.

Options

Field	Default	Meaning
`export`	—	The export payload to import.
`mapping`	required	`fields`, plus optional `source_type` (`bucket` or `collection`) and `chain_template`.
`explode`	`null`	Split one export row into several documents. `explode_axis` names the doc-generating array, for example `scene_content`.
`dry_run`	`false`	Reconstruct and validate without writing.
`seed_ledger`	`false`	Seed the ledger alongside the import.

Documents & Search for the single-call BYO upsert
Collection Lifecycle

​Reading the result

​Options

​Related

Reading the result

Options

Related