Skip to content

Bulk Import -- File Format & Naming

Bulk import files are provided as CSV files packaged inside a single ZIP archive.

Each CSV file maps to exactly one table using the table's API name.

Archive Rules

  • Exactly one ZIP file per import
  • ZIP may contain multiple CSV files
  • No nested folders
  • Only CSV files are processed

Table File Naming

Table Type File Name Format
Regular table <table-api-name>.csv
Many-to-many relation <source-table>-<relation>.csv

File names must match the API names exactly. Case-sensitive.

Example ZIP File Layout

The ZIP archive contains only CSV files at the root level. Each file maps to a table or a many-to-many relation.

import.zip
├── person.csv
├── address.csv
├── company.csv
├── person-address.csv
├── employee-roles.csv


- `person.csv`, `address.csv`, `company.csv` → regular tables  
- `person-address.csv`, `employee-roles.csv` → many-to-many relation files  
- No subdirectories are allowed  
- Only `.csv` files are processed

CSV Format

  • RFC 4180 compliant
  • UTF-8 encoded
  • Comma-separated
  • Header row is mandatory
  • Empty values are interpreted as null

Mandatory Columns

Regular Tables

  • _operation
  • id
  • _id

Many-to-Many Tables

  • _operation
  • source
  • _source
  • target
  • _target

Operation Column

The _operation column controls the executed action per row:

  • INSERT
  • UPDATE
  • DELETE

NOTE

Only INSERT and DELETE are permitted in many-to-many link files.