Schema & Data

As seen in the Entities, Relations, Attributes page, a TypeDB schema defines a hierarchy of types, their associated interfaces and interfaces they implement.

Data is created by instantiating types from the schema. Hence, it is impossible to create data not conforming to the types declared in the schema. Connections made between instances are also checked against the owns, plays, and relates in the schema to ensure they are permitted between the instance types. Write & commit time validation ensures that any constraints that also depend on the state of the database (such as cardinality constraints on updated connections) are respected. Through this type-checking and validation, TypeDB guarantees semantic integrity of the database.

Inserting data

The TypeQL insert clause is used to insert new instances, the attributes owned by these instances, and the relations linking them.

Inserting new instances

New instances are inserted using an isa constraint specifying the type. To insert an attribute, its value must also be specified.

insert
  $person isa person;
  $employment isa employment;
  $age isa age 10;

Inserting a new instance will fail if the type is abstract. In the case of attributes, the value must also be of the value-type specified by the attribute, and satisfy all value constraints defined on the type.

Remember that inserted entities and relations don’t have a natural identifier in your domain unless you provide one. The caveat here is that TypeDB generates an instance ID (iid, which you’ll see in output logs) for your inserted entities and relations. However, it is recommended that you create meaningful identifiers, especially keys, when needing to refer to specific entities or relations.

Now we will see how to create ownerships for attributes & link role players to relations.

Inserting ownerships

An ownership between an entity (or relation) and an attribute is inserted using a has constraint:

insert
  $person isa person;
  $age isa age 10;
  $person has $age;

Or in one line:

insert $person isa person, has age 10;

This insert succeeds only if the type person "owns" the type age in the schema. That is, the constraint person owns age; was defined in the schema, or person inherits owns age from its supertype.

Unless their types are declared @independent, attribute instances which are not involved in any ownerships are cleaned up at the end of a transaction.

Linking role players

Since relations exist to "link" instances together, these links between the relation are role players are typically inserted along with the relation:

insert
  $company isa company;
  $person isa person;
  $employment isa employment;
  $employment links (employer: $company);
  $employment links (person: $person);

Inserting $employment links (employer: $company) succeeds only if the type company plays the employer role defined by the employment relation. Similarly, the type person must play the employment:employee role for $employment links (person: $person); to be inserted.

TypeQL has shorthands for writing queries in a more concise & natural manner.

E.g., The two links constraints on $employment can be combined into one. The combined links and isa constraint can then be written together with a comma.

insert
  # ...
  $employment isa employment,
    links (employer: $company, employee: $person);