TypeDB 3.0 is live! Get started for free.

Updating data

This page explains how to update data in a TypeDB database.

Overview

Data in TypeDB is updated using update or a combination of delete and insert stages in write pipelines, which can executed in write (or schema) transactions. It can be used in a pipeline to operate variables declared on a preceding stage.

Due to safety reasons, only unambiguous statements are allowed in update stages. Thus, it can only operate on has and links statements with their schema cardinalities limited by 1. To have more available actions and manual control over updates, use deletion and insertion instead.

Update queries replaces the existing data with the values specified. The new data insertion happens even if no data existed before the update.

This way, update stages can be used to ensure that the data is in a required state before proceeding with other pipeline stages, ignoring the previous "wrong" state of the database.

Refer to the Update stage page for a detailed explanation and additional examples.

Running updates

To update data, open a write transaction. This allows you to read and write data to your database while keeping the schema secure.

Update stages begin with the keyword update. Multiple statements can be combined within the same update stage and the same variable may appear in multiple statements.

Update statements

Let’s give a brief overview of what kinds of statements can be used in an update stage.

Updating attribute ownerships with has

Connections of attributes to their “owner” data instances can be updated using has statements.

Updating a single user’s username using a value constant
match
  $x isa user, has username "User_1";
update
  $x has username "User_2";

If the username attribute "User_2" does not yet exist when running the above, it will be created anonymously by the above query (“anonymously” meaning that we do not assign it to any variable). However, no explicit isa statements for variable binding are allowed in updates.

Similarly, an attribute variable can be used in this operation.

Updating a single user’s username using an attribute variable
match
  $x isa user, has username "User_1";
  $y isa username "User_2";
update
  $x has $y;

Without update stages, you’d be required to write two other stages instead.

Updating a single user’s username through delete and insert
match
  $y isa username "User_2";
  $y-old isa username "User_1";
  $x isa user, has $y-old;
delete
  has $y-old of $x;
insert
  $x has $y;

Connections of relations to their “role players” data instances can be updated using links statements.

Updating all existing group memberships of a user with a new group
insert
  $g isa group, has group-id "Group_2";
match
  $x isa user, has username "User";
  $gm isa group-membership, links (member: $x);
update
  $gm links (group: $g);

If a role player can only play a single role in the relation, the role can be omitted.

Updating all existing group memberships of a user with a new group without updated role specification
insert
  $g isa group, has group-id "Group_2";
match
  $x isa user, has username "User";
  $gm isa group-membership, links (member: $x);
update
  $gm links ($g);

As already mentioned, update stages are useful to write shorter queries. It is especially noticeable in queries updating multiple things. For example, swapping role players after a mistaken insertion.

Using an update stage to swap role players
match
  $p isa parentship (parent: $x, child: $y);
update
  $p links (parent: $y, child: $x);

Update stage answers

An update stage does not modify the input variables from the previous stages. Thus, it returns a stream of the same concept rows produced by a preceding pipeline stage.

Update example’s result
   ------------
    $g  | iid 0x1f00020000000000000001 isa group
    $gm | iid 0x1e00030000000000000000 isa group-membership
    $x  | iid 0x1e00030000000000000003 isa user
   ------------

Committing

Do not forget to commit your transaction to preserve the changes.

Some data constraints are only validated upon commit. This means you might discover inconsistencies in your data during the commit process, and the commit will be rejected.

While most validations occur during operation time to keep data synchronized, commit-time validations are necessary to allow flexible data modifications. For example, validating inserted data against cardinality during operation time could block modifications entirely.

If you want to abort your changes, simply close the transaction or perform a rollback. Refer to Transactions for more details.

Having troubles?

Refer to the Debugging queries page for common debugging tips.