Writing data

There are multiple query types that can modify data in a TypeDB database:

To send a writing data query we need to use Write transaction.

All examples provided on this page are designed for the IAM database schema and data. To set the IAM database follow the Quickstart guide.

Insert query

An Insert query is used to add new data to a TypeDB database.

Data can be inserted only as an instances of a type, existing in the database schema.

Syntax

Insert queries are written in TypeQL with the following syntax:

[match <pattern>]
insert <pattern>

Behavior

See the Insert query section of the Queries page.

Examples

A simple insert example:

insert $p isa person, has full-name "Bob";

A simple example with match clause:

match
  $f isa file, has path "README.md";
insert
  $f has size-kb 55;

In the above example we matching an instances of file entity type that have attribute of path type with the value README.md, and then we inserting an ownership of size-kb attribute with value 55 to every matched entity.

A more complex example:

match
  $s isa subject, has full-name "Pearle Goodman";
  $o isa object, has path "zewhb.java";
  $a isa action, has name "modify_file";
  $ac (object: $o, action: $a) isa access;
insert
  $p (subject: $s, access: $ac) isa permission;

The above query:

  1. Finds a subject ($s) whose full-name attribute has a value of Pearle Goodman.

  2. Finds an object ($o) whose path attribute has a value of zewhb.java.

  3. Finds an action ($a) whose name attribute has a value of modify_file.

  4. Finds an access relation ($ac) that relates the $o (as access-object) to $a (as action).

  5. Inserts a permission relation that relates $s (as subject) to the relation $ac (as access).

In the IAM database this query should only insert a single instance of data of the permission type. But if any statements in the match clause will match multiple results (e.g., if we insert a second instance of subject type with owned full-name attribute of the Pearle Goodman value) the query can result if multiple inserts. One for every matched pattern.

Delete query

A delete query can be used to remove data from a TypeDB database.

We can remove instances of types as well as references to them, like attribute ownerships.

Syntax

A delete query is always preceded by a match clause as we need to locate the existing data to delete first.

Delete queries are written in TypeQL with the following syntax:

match <pattern>
delete <pattern>

Behavior

See the Delete query section of the Queries page.

Examples

A simple example:

match
  $p isa person, has full-name "Bob";
delete
  $p isa person;

In the above query, match clause finds every person entity owning a full-name attribute with the value of Bob. Then, it removes the matched entities.

A more complex example:

match
  $p isa subject, has full-name "Pearle Goodman";
  $a isa action, has name "modify_file";
  $ac (object: $o, action: $a) isa access;
  $pe (subject: $p, access: $ac) isa permission;
delete
  $pe isa permission;

The above query does the following:

  1. Finds a subject entity ($p), with full-name attribute value of Pearle Goodman.

  2. Finds an action entity ($a), with name attribute value of modify_file.

  3. Finds access relations ($ac) relating any object (as object) to the action $a (as action).

  4. Finds permission relations ($pe) relating the subject entity $p (as subject) to the access relations $ac (as access).

  5. Deletes all matched permissions $pe.

In short, it removes all of the permissions that let Pearle Goodman to modify files.

Update query

An update query is just a match-delete-insert. It removes and then adds data based on the match, delete, and insert patterns.

Syntax

Updates are written in TypeQL with the following syntax:

match <pattern>
delete <pattern>
insert <pattern>

Behavior

See the Update query section of the Queries page.

Examples

A simple example:

match
  $p isa person, has full-name "Masako Holley", has email $email;
delete
  $p has $email;
insert
  $p has email "[email protected]";

The above query, does the following:

  1. Finds all person entities ($p) that have a full-name attribute with a value of Masako Holley and have email attribute.

  2. Deletes an ownership of $p over its current email attribute. Take a note, that it happens regardless of its value.

  3. Makes $p the owner of an email attribute with a value of [email protected].

If the person with such a full-name had more than one email, then the match clause produce more than one match and both delete and insert clauses will be executed once per match. But a type can’t own an attribute instance more than once. Hence, the result will be the same — only one email owned.

A more complex example:

match
  $p isa person, has full-name "Pearle Goodman";
  $a_write isa action, has name "modify_file";
  $a_read isa action, has name "view_file";
  $ac_write (object: $o, action: $a_write) isa access;
  $ac_read (object: $o, action: $a_read) isa access;
  $pe (subject: $p, access: $ac_write) isa permission;
delete
  $pe (access: $ac_write);
insert
  $pe (access: $ac_read);

The above query does the following:

  1. Finds a person entity ($p) with a full-name of Pearle Goodman.

  2. Finds an action entity ($a_write) with name of modify_file).

  3. Finds an action entity ($a_read) with name of read_file).

  4. Finds access relation ($ac_write) that relate an object (as object) to the $a_write (as action).

  5. Finds access relation ($ac_read) that relate an object (as object) to the $a_read (as action).

  6. Finds permission ($pe) that relate $p (as subject) to $ac_write (as access).

  7. Removes the $ac_write as a player of the access role in the $pe.

  8. Adds the $ac_read as a player of the access role in the $pe.

In short, all of Pearle Goodman’s permissions with write access will become permissions with read access.

After running the above query, all of the matched access relations $ac_write with $a_write as action still exist, but no longer play a role in the matched permission relations.

Learn more

After we write some data into the database, we can try to read it.

In case there is no dataset ready yet for insertion, see the IAM sample dataset for examples.