Skip to content

title: "Bulk import identifiers" description: "Bulk import uses explicit identifier fields to resolve which rows are created, updated, or deleted." This page defines the supported identifier types, their...

Bulk import identifiers

Bulk import uses explicit identifier fields to resolve which rows are created, updated, or deleted.
This page defines the supported identifier types, their precedence rules, and how they apply to different operations and relation types.

Identifier resolution is deterministic and evaluated independently for each row.

Identifier fields

Bulk import supports two identifier fields on all tables:

  • id
    Internal, immutable system identifier.

  • _id
    External, mutable reference identifier supplied by the importing system.

Both identifier columns must exist in all bulk import files, even if their values are empty.

Resolution rules

Row resolution follows these rules:

  • If id is present, it is always used as the primary lookup key.
  • If only _id is present, the row is resolved using _id.
  • If both id and _id are present:
  • id is used for lookup
  • _id is updated if a value is provided
  • If neither identifier is present:
  • INSERT is allowed
  • UPDATE and DELETE are rejected

Resolution is performed per row and does not depend on other rows in the file.

When id / _id is required

Identifier requirements depend on the operation:

  • INSERT
  • id and _id may both be empty
  • UPDATE
  • at least one of id or _id must be present and resolvable
  • DELETE
  • at least one of id or _id must be present and resolvable

Rows that do not meet these requirements produce row-level errors.

Operations

The _operation column controls how identifiers are interpreted:

  • INSERT
  • creates a new row
  • identifiers may be omitted
  • UPDATE
  • modifies an existing row
  • requires resolvable identifiers
  • DELETE
  • removes an existing row
  • requires resolvable identifiers

Operation handling is non-transactional across rows.

Constraints

The following constraints apply:

  • identifier precedence is fixed and cannot be overridden
  • identifier resolution is evaluated independently per row
  • unresolved identifiers produce row-level errors only
  • many-to-many link files do not support UPDATE
  • identifier semantics are identical in dry run and execution

Identifier behavior is consistent across bulk import phases.

Related concepts