docs
/
AI skills

Import records into a collection

Bring rows from a CSV or JSON file (or pasted rows) into a collection as a background import job, map the columns to fields, and follow it on the Jobs screen. Export works the same way in reverse.

An import never runs inside the request: it becomes a job that works through the file in batches of 1,000 rows, so a large file does not slow anything else down. When it ends, the person who asked gets an email and a notice, and the job shows what happened.

Ask first

  • Which collection? An existing one, or a new one made from the file's columns.
  • The file or the rows. CSV or JSON only. Excel files must be saved as CSV first.
  • Which column goes into which field, when the column names don't match the field names.
  • Add or update? Always add new records, or match each row on a field (or on the record id from an earlier export) and update that record.
  • Check first? Whether to validate only (nothing is written) before the real import.

Customers and staff accounts cannot be imported this way. The import refuses them, because an account needs a password, a welcome and the sign-up checks. Customers go through customer sign-up. Staff go through invitations.

Steps

1. Collection builder: the target collection

If the collection exists, open it in the Collection builder (/collection-builder with name = the collection's name) and read its fields. If it doesn't exist and the person wants one, create it first (see Shared form from a collection, step 1). The name uses lowercase letters, digits and _, and is at most 20 characters.

Hands on: the collection's name and its field names. Check: the collection opens with the fields the rows will fill.

2. Data import: map the columns and start the job

On screen: open the collection's table and press Import, or use Database → Import Data. The wizard opens with the collection already chosen. Choose File Upload or Paste JSON or CSV, match each column to a field (leave a column as ignore to drop it), then on the summary step:

  • Validate only checks every row and writes nothing;
  • Update existing records picks the field to match on. Record id means that re-importing an export updates the records it came from.

Real action: POST repository/bulk-create with { format: 'csv' | 'json', datatype: '<collection name>', sourceCollection, file: { path } | data, dryRun?, upsertKey? }.

  • A file into an existing collection: upload the file first (POST repository/file/upload), then pass file.path. Every column passes through under its own name.
  • Pasted rows into an existing collection: sourceCollection.data.schema.properties must give each column a target field. A column with no target is ignored, and if no column has a target, every row is skipped.
  • The call answers at once with the import report and the job.

Hands on: the job id. Check: the answer carries a job in status queued or running. A mapping error (a target field the collection doesn't have) comes back straight away. Fix it and start again; nothing was written.

3. Jobs: watch it finish

Open Jobs (/jobs?id=<job id>). The job shows its progress bar, ETA and counts: created, updated, skipped and failed. Its drawer lists the first 100 rows that failed, each with the reason. Cancel stops after the batch it is working on, and what was written stays. Retry carries a failed or cancelled job on from where it stopped.

Check: the job is done. Its counts add up to the rows in the file. Open the collection and confirm that a few of the rows are there with the right values. If it was a validate-only run, say so plainly ("checked only, nothing written") and ask before the real import.

Export

On screen: the collection's table → Export downloads the file straight away (all rows, or only the ticked ones).

Real action: POST repository/export/<collection name>?background=true with { format: 'csv' | 'json', query?, fields? }. This starts an export job and answers with it. Use background=true when the AI does the export. Without it, a small export comes back as file text inside the reply, and the person gets no file. Exports over 100,000 rows always run as a job.

  • The file is written to the organisation's private file storage. Nobody can open it without a signed link.
  • When the job ends, the Jobs drawer shows Download. The person who asked also gets the same link by email and in a notice.
  • The link works for 7 days. After that, run the export again.
  • Never copy the file into the public File Manager to make it easy to share.

Check: /jobs?id=<job id> is done, shows the row count and has a Download button.

When it's done

Tell the person:

  • which collection;
  • how many rows were created, updated, skipped and failed, and the reason for any failures;
  • whether it was a check only.

Open the job on the Jobs screen. For an export, give the row count, say the download is on the job and in their email, and say the link lasts 7 days.