Skip to content

title: "Bulk import format" description: "Bulk import consumes CSV files packaged in a single ZIP archive." This page defines how files must be structured, named, and parsed for the import to be acc...

Bulk import format

Bulk import consumes CSV files packaged in a single ZIP archive.
This page defines how files must be structured, named, and parsed for the import to be accepted and processed.

Only files that fully comply with these format rules can pass structural validation.

File structure

A bulk import consists of exactly one ZIP archive.

Rules for the archive:

  • exactly one ZIP file per import
  • the ZIP may contain multiple CSV files
  • all CSV files must be located at the root level
  • no subdirectories are allowed
  • only .csv files are processed

Each CSV file maps to exactly one target: either a table or a many-to-many relation.

File-to-target mapping is determined solely by the file name.

Required columns

Every CSV file must include a header row.

Regular tables

CSV files targeting regular tables must include the following columns:

  • _operation
  • id
  • _id

All three columns are mandatory, even if the values are empty.

Many-to-many relation files

CSV files targeting many-to-many relations must include:

  • _operation
  • source
  • _source
  • target
  • _target

Each row represents exactly one relation edge.

Special columns

_operation

The _operation column defines the mutation applied for each row.

Supported values:

  • INSERT
  • UPDATE
  • DELETE

Operation constraints:

  • UPDATE and DELETE require a resolvable identifier
  • many-to-many files only allow INSERT and DELETE
  • invalid operations are rejected during validation

Identifier columns

Identifier columns are used to resolve target rows:

  • id → internal system identifier
  • _id → external reference identifier

For relations, equivalent identifier pairs apply:

  • <relation> / _<relation>
  • source / _source
  • target / _target

Resolution rules are defined in the identifiers reference.

Parsing rules

CSV files are parsed using the following rules:

  • RFC 4180 compliant format
  • UTF-8 encoding
  • comma-separated values
  • header row is mandatory
  • empty values are interpreted as null
  • column names are case-sensitive
  • column names must match schema API names exactly

Parsing occurs before any dry run or execution logic is applied.

Common errors

Format-related errors are detected during structural validation.

Typical causes include:

  • missing mandatory columns
  • incorrect file names
  • invalid CSV structure or encoding
  • unknown column names
  • unsupported operations for the target file type

Structural validation errors prevent the import from proceeding.

Row-level data errors are handled separately during dry run and execution.

How-to

Related concepts