custodian records import

custodian records import loads many records from a CSV file in one run. Every client_encrypted field is sealed on your machine before it is sent, exactly as records create does one at a time. Be signed in, have a schema applied, and — because encrypting locally needs it — an enrolled device.

custodian records import policies --file policies.csv --map policies.map.yaml

• <collection> — the primary collection the file is about; it must appear in the map.
• --file <csv> — the CSV file to import (required).
• --map <yaml> — a YAML file mapping CSV columns to schema fields (required).

The mapping file

The map names, per collection, which CSV column carries each schema field, which column carries the record's external_ref, and — for a child collection — which column carries the parent's external_ref:

collections:
  policies:
    external_ref: policy_id
    fields:
      policy_number: PolicyNo
      holder_tax_id: TaxId

Every collection must map an external_ref column. That is the business key Custodian uses to recognise a row it has already imported, so a second run does not duplicate it.

Checking before sending

Custodian validates the whole file against the schema and the map before it encrypts or sends anything, and reports every problem at once — an unknown column, a missing required field, a value that does not fit its field's type, a duplicate external_ref, a child whose parent is neither in the file nor already in the vault. If there are problems, nothing is sent:

error: The import was refused; nothing was encrypted or sent. 2 problems found:
  - Collection "policies" maps field "premium", which its schema does not declare.
  - Collection "policies" row "PY-4471" (CSV line 12) is missing required field "policy_number".

--dry-run runs that validation and reports what would be imported, encrypting and sending nothing.

Resuming an interrupted run

If a run is interrupted, --resume picks up where it stopped: it reads a resume file recording which rows were already imported and re-encrypts only the rest. The resume file holds only external_ref values — no value, key or ciphertext — so losing it costs a re-run, not a disclosure.

custodian records import policies --file policies.csv --map policies.map.yaml --resume

--resume-file <path> overrides the resume file's location (it defaults to <file>.resume).

If the schema version changes while a run is in flight, the run stops — the rows already sealed cannot be retried under the new version — and tells you to re-run with --resume to re-encrypt the remainder.

Other options

• --concurrency <n> — how many create requests to send at once (default 8).
• --json — machine-readable output.

When it finishes

120 records
240 values encrypted locally (holder_tax_id, premium)
120 policies
0 bytes of plaintext transmitted for client_encrypted fields