Update query

This documentation is not current - it is for TypeDB 2.x, which is no longer supported. View the documentation for TypeDB 3.x:

An Update query is used to replace data in a TypeDB database. This query deletes and then inserts data based on a given match, delete, and insert patterns. For a practical guide on how to send an Update query to TypeDB, see the Update query page of the TypeDB Manual.

Syntax

An Update query consists of a match, delete, and insert clauses:

match <pattern>
delete <delete_pattern>
insert <insert_pattern>

where both <delete_pattern> and <insert_pattern> are patterns of valid data-specific TypeQL statements including isa / isa!, has, role assignment, and value assignment.

The mandatory match clause <pattern> can be any valid match pattern: for more information, see the Patterns and Statements sections.

Behavior

An Update query first deletes and then inserts data instances, ownerships, or role player assignments to a database. The results of the match clause in an Update query will be used for the variables in its subsequent delete and insert clauses. For more information and examples of the latter clauses, see the Delete query and Insert query page.

Note that inserted data need not be a direct replacement for the data deleted by the same query. You can insert a new concept instead of a deleted one with either the same variable or a new one.

Query execution

The insert clause is executed after the delete clause of the same query and uses the same matched result from the match clause. For an Update query to succeed the following must be satisfied:

  • Data that is assumed to exist insert must not be deleted in the preceding delete clause. For example, deleting an entity and then trying to insert ownership of an attribute to that deleted entity (and without inserting a new entity its place).

  • Inserted data must not violate a schema of a database.

Query response

An Update query returns a lazy Stream/Iterator of ConceptMap with the inserted data.

Update ownerships

For this example, use a database with the IAM schema and sample data loaded.

In many cases, the desired effect is to change the value of an owned attribute. Attributes are immutable, and we can’t change a value of an attribute. But we can replace ownership: delete ownership of the old attribute and add a new one.

Replacing ownership
match
$p isa person,
    has full-name "Masako Holley",
    has email $email;
delete
$p has $email;
insert
$p has email "m.holley@typedb.com";

The above query does the following:

  1. Matches all person entities ($p) that have the full-name attribute with the value of Masako Holley amd have some $email of type email.

  2. Deletes from $p ownership of its matched email attribute.

  3. Makes $p the owner of the email attribute with the value of m.holley@typedb.com.

If there are more than one $email found for Masako Holley person, than there will be more than one result for the match clause. Both delete and insert clauses will be executed once for every matched result (for every $email). Inserting multiple ownerships of the same attribute for the same owner produces the same result as inserting one.

The old email attribute with the value of masako.holley@typedb.com will still exist, but it will no longer be owned by the person entity.

If you want to narrow down the matched results to a single unique entity, consider specifying uniqueness annotation for some of its attribute ownerships.

Update attributes

For this example, use a database with the IAM schema and sample data loaded.

Deleting an attribute deletes ownership of it from all its owners. We can insert a new attribute instead of a deleted one without a problem, because we match all data with a match clause pattern before we start deleting and inserting.

Replacing attribute
match
$p isa person, has full-name $n;
$n contains "inappropriate word";
delete
$n isa full-name;
insert
$p has full-name "deleted";

The above query:

  1. Finds all person entities ($p) with at least one owned full-name attribute ($n).

  2. Filters $n (and consequently $p) to only those that contain the substring inappropriate word.

  3. Removes these full-name attributes that contain the substring from a database.

  4. Makes $p the owner of the full-name attribute with the value of deleted.

Assuming there are some matches, after running the above query, there will be a single full-name attribute with a value of deleted, which is owned by the matched entities. Any full-name attributes which contained the substring inappropriate word will no longer exist in the database.

Update role players

For this example, use a database with the IAM schema and sample data loaded.

To replace a role player, we combine the steps for deleting a role player with extending the relation:

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 the person entity ($p) with the full-name of Pearle Goodman.

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

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

  4. Finds all access relations ($ac_write) that relate any object (as object) to $a_write (as action).

  5. Finds all access relations ($ac_read) that relate any object (as object) to $a_read (as action).

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

  7. Removes all write accesses ($ac_write) as a player of the access role in matching permission relations ($pe).

  8. Adds all read accesses ($ac_read) as a player of the access role in matching permission relations ($pe).

In short, all of Pearle Goodman’s permissions with the modify_file access become permissions with the view_file access.

After running the above query, all 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

Lesson 4.4: Updating data

Learn more about updating/replacing data in a database in TypeDB Academy.

Update query

See how to send an Update query to TypeDB.