Officially out now: The TypeDB 3.0 Roadmap >>

Insert stage

An insert stage inserts new data into the database. Insertable data includes instances of types, ownerships of attributes, and role players of relations.

Syntax

The body of an insert stage is a sequence of insert statements.

All insert statements have the same syntax as their corresponding match statements.

insert <insert-statement> [ <insert-statement> ... ]

Behavior

  • Isa statements insert new instances of specified types. Each variable introduced in the insert clause must be accompanied by an explicit isa statement.

  • Has statements insert new ownerships of attributes. If an attribute is provided by value, the attribute type is mandatory.

  • Links statements insert new role players for relations. Role tags must be provided for all players.

Execution

If the insert stage is the first stage in a write pipeline, its body is executed once. The output stream in that case contains a single row containing the newly inserted concepts.

If the insert stage is preceded by other stages, its body is executed once for each input row. The output is then a stream of input rows extended with the newly inserted values.

Validation

Attempting to insert the following fail immediately and terminate the transaction:

  • an instance of an abstract type,

  • an ownership or a role player that does not conform to the schema ( a player of a relation that cannot relate a role with the specified role name, a player of a type that cannot play the specified role type, an ownership for the owner that cannot own an attribute of the specified type),

  • an instance of an attribute type with a value that violates a constraint annotation (@range, @regex, @values),

  • an ownership that violates a constraint annotation (@distinct, @key, @unique).

Cardinality annotations are not enforced until the transaction is committed.

Examples

insert
  $group isa group,
    has group-id "<group id>";
  $person isa person,
    has name "<name>",
    has bio "<bio>",
    has profile-picture "<uuid>";
  group-membership(group: $group, member: $person) has rank "member";
match
  $person isa person, has name "<name>";
  $group isa group, has group-id "<group id>";
insert
  group-membership(group: $group, member: $person) has rank "member";