Developers · Data
Data Import/Export Introduction
Last updated 1 November 2026
The ways to move data into and out of an Insites instance, and how to choose between them.
Insites gives you several ways to move data into and out of an instance. The right one depends on how much data you move and whether you need all of it. It also depends on whether a person or a script does the work.
Choose a method
| Method | Moves | Use it for |
|---|---|---|
insites-cli data export and data import | All the data on the instance | Backups, and copying a whole instance to another one |
The data_export mutation | Records, users or both, selected with a filter, as CSV files in a zip | Exporting part of the data from code |
import_models and import_users | Records or users you send in the call | Loading data from code or from another system |
| A migration | Whatever its Liquid writes | Small seed data, such as default categories |
Example: back up an instance
insites-cli data export staging -p data/staging.zipThis writes every record and user on the instance to a zip. Import it into another environment with:
insites-cli data import dev -p data/staging.zip --zipdata import reads a JSON file, or a zip archive with --zip. It does not read CSV, and it has no table option: the CLI always works on the whole instance.
Ids and related records
By default an import remaps ids. The ids in your file are stored as external ids, new objects get new ids, and references between the imported objects are rewritten to match. Pass --raw-ids on the CLI, or _id_remap: false in GraphQL, to keep the given ids. Raw ids must be integers.
Danger
insites-cli data clean removes all users and records on the instance, not one table. It cannot be undone. Export first.
Common mistakes
- Trying to import a CSV file with the CLI. Use JSON, or a zip with
--zip. - Using a migration for a large import. Migrations suit seed data; use import for volume.
- Matching imported users to their new ids by position. Match on external id or email.