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 can be omitted if there is only a single role the role player can play.

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

Schema for the following examples 
#!test[schema, commit]
define
  entity content owns id;
  entity page sub content,
    owns page-id,
    owns name;
  entity profile sub page,
    owns username;
  entity user sub profile,
    owns phone,
    owns karma;

  attribute id value string;
  attribute page-id sub id;
  attribute username sub page-id;
  attribute name value string;
  attribute phone value string;
  attribute karma value double;
attribute bio value string;
attribute profile-picture value string;
attribute email @independent, value string @regex("^.*@.*\.com");
user owns bio, owns profile-picture;
attribute group-id sub id;
attribute rank, value string @values("admin", "member");
attribute tag value string;
relation group-membership, relates group, relates member,  owns rank;
entity group, owns name, owns group-id, owns tag, plays group-membership:group;
user, plays group-membership:member;
#!test[write, documents]
insert
  $group isa group,
    has group-id "<group id>";
  $user isa user,
    has name "<name>",
    has bio "<bio>",
    has profile-picture "<uuid>";
  group-membership(group: $group, member: $user) has rank "member";
#!test[write]
match
  $user isa user, has name "<name>";
  $group isa group, has group-id "<group id>";
insert
  group-membership(group: $group, member: $user) has rank "member";