Skip to content

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

MethodMovesUse it for
insites-cli data export and data importAll the data on the instanceBackups, and copying a whole instance to another one
The data_export mutationRecords, users or both, selected with a filter, as CSV files in a zipExporting part of the data from code
import_models and import_usersRecords or users you send in the callLoading data from code or from another system
A migrationWhatever its Liquid writesSmall seed data, such as default categories

Example: back up an instance

insites-cli data export staging -p data/staging.zip

This 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 --zip

data 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.