TypeDB 3.0 is live! Get started for free.

Deleting data

This page explains how to delete data from a TypeDB database.

Overview

A delete stage is used to delete data from a TypeDB database. It can be used in a pipeline to operate variables declared on a preceding match stage.

Refer to the Delete stage page for detailed explanation and more examples.

Running deletes

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

Delete stages begin with the delete keyword. They also require input data: for each row in the input the delete statements in the body of the delete stage will be executed.

A delete stage produces output rows by removing from each input row the concepts that are deleted when applying the stage’s delete statements to that input.

In some circumstances, when a data instance is deleted for one input row, it may still appear in other input rows in non-deleted form. Using deleted instances after they were deleted will lead to a runtime error.

Delete statements

Deleting instances

To delete a data instance (an entity, a relation, or an attribute), declare a $var for this instance and add delete $var:

User deletion example
match
  $u isa user, has username "User";
delete
  $u;

The pipeline will act in two stages:

  • The first stage will match all user s with username "User"

  • The second stage will delete the matched user s

Deletes may cascade: when deleting instance, relations and attributes that reference these instance may be cleaned up on commit.

  • relations without role players will be cleaned up.

  • attributes without owners will be cleaned up (unless their attribute type is marked as independent).

For example, the @independent annotation can help preserving attributes (username) in the database even if their owners are deleted.

Delete ownership references

To delete only a specific ownership reference, connecting an attribute to an owner, mention what you want to delete and what instance it relates to. In case of an ownership instance, write an expression like has $attribute of $owner using the has statement and the keyword of pointing to the owner:

User’s ownership of an attribute deletion example
match
  $a isa user, has username "Alice", has email $email;
delete
  has $email of $a;

This query only deletes the owner reference between $email and $a, not the attribute itself! However, if email s are not @independent and there are no users with this email on commit, the attribute will be cleaned up.

Delete player references

Similarly, a connection between a relation and its role players can be deleted. A single role or multiple roles can be deleted using the following query:

Deletion of a relation linking example
match
  $b isa user, has username "Bob", has email "bob@typedb.com";
  $c isa user, has username "Charlie", has email "charlie@typedb.com";
  $f isa friendship, links (friend: $b, friend: $c);
delete
  links ($b, $c) of $f;
  links ($b) of $f;

The has and links keywords are, in face, optional in delete stages. They may sometimes be required for ambiguity resolution and generally improve readability.

Response interpretation

A delete stage takes the input from the previous pipeline stages, processes the deletions and returns the concepts remaining from the input. Deleted concepts are not shown in the produced output row. This way, another pipeline stage can take this as an input and continue data processing.

For example, the example of a user instance deletion where there are no concepts left for the output produces the following TypeDB Console’s response:

Result with empty columns
No columns to show

At the same time, a has deletion does not affect the output, as both concepts are still in the database until a commit:

Result after a has deletion
   ------------
    $email | alice@typedb.com isa email
    $u     | iid 0x1e00030000000000000002 isa user
   ------------

However, if you delete the email itself:

Result after an attribute deletion
   ------------
    $u     | iid 0x1e00030000000000000002 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.