Skip to content

title: "Bulk import relations" description: "Bulk import supports relation mutation across all relation types." Relations are resolved using relation API names and the same identifier resolution rules ...

Bulk import relations

Bulk import supports relation mutation across all relation types.
Relations are resolved using relation API names and the same identifier resolution rules used for rows.

Relation handling is evaluated per row and does not require transactional consistency across files.

Relation imports overview

Relations are represented differently depending on their cardinality.

For one-to-one, one-to-many, and many-to-one relations, the relation is expressed as a foreign-key reference in the importing table.

For many-to-many relations, relations are imported using dedicated link files.

In all cases, the relation API name used in bulk import is the API name defined from the source table to the target table.

Many-to-many files

Many-to-many relations are imported through dedicated link files.

File naming

Link files must follow this format:

<source-table-api-name>-<relation-api-name>.csv

The source table and relation API name must match the schema exactly.

Required columns

Each link file must contain the following columns:

  • _operation
  • source
  • _source
  • target
  • _target

Each row represents exactly one relation edge between two rows.

Semantics

  • INSERT
    Creates a relation between the resolved source and target rows.

  • DELETE
    Removes the relation between the resolved source and target rows.

  • UPDATE
    Not permitted for many-to-many relations.

Allowed operations

Allowed operations depend on relation type:

one-to-one / one-to-many / many-to-one:

  • INSERT
  • UPDATE
  • DELETE

many-to-many:

  • INSERT
  • DELETE

Operations are evaluated per row and are not transactional across files.

Common errors

Typical relation-related errors include:

  • unresolved source or target identifiers
  • incorrect relation API names
  • invalid link file naming
  • unsupported operations for the relation type

Relation errors affect only the failing rows and do not block unrelated row or relation processing.

Related concepts