Delete query

A delete query removes data from a database.

It can be used to remove entities, relations, and attributes as well as references to them, like attribute ownerships.

For example, to remove ownership of an attribute without deleting the attribute itself or to remove the player of a role from a relation without deleting either the player or the relation/role.

Syntax

Delete queries are written in TypeQL with the following syntax:

match <pattern>
delete <pattern>

The Delete query is always preceded by a match clause.

The match clause uses a pattern to find existing data/references that can be used in the delete clause.

The delete clause uses a pattern to specify which data/references that were found by the match clause should be removed.

A pattern consists of variables and constraints for concepts. For more information, see the Pattern syntax section.

The number of deleted concepts depends on the number of answers matched by the match clause. The delete clause will be executed once per every matched answer.

If there are no matches for a match clause in a delete query, then there will be no deletes.

Prior to TypeDB v.2.22.0, a delete query would fail (throw an error) if its delete clause would try to delete a previously deleted or non-existent data.

The delete clause can have multiple statements in its pattern to delete in one query. But it can’t delete types (use undefine to delete types) and can’t have the following:

  • Conjunction

  • Disjunction

  • Negation

  • is keyword

Entities

Use a match clause followed by the delete keyword and a pattern containing an isa statement to remove an entity from a database.

match
  $p isa person, has email "[email protected]";
delete
  $p isa person;

In the above query, match clause finds a person entity (or entities) owning an email attribute with a value of [email protected]. Then, it removes the matched entities and all associated ownerships.

Relations

Instances

Use a match clause followed by the delete keyword and a pattern containing an isa statement to remove a relation from a database.

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 the permissions that let Pearle Goodman modify files.

Role players

Use a match clause followed by the delete keyword and a pattern to remove a player from a role in a relation.

match
  $p isa subject, has full-name "Masako Holley";
  $o isa object, has path "zewhb.java";
  $oo (owner: $p, owned: $o) isa object-ownership;
delete
  $oo (owner: $p);

The above query, assuming the full-name attribute is unique for each subject entity and the path attribute unique for each object:

  1. Finds a subject entity ($p, Masako Holley).

  2. Finds an object entity ($o, zewhb.java).

  3. Finds an owner relation ($oo) relating $p (owner) to $o (owned).

  4. Deletes $p as a player of the owner role in $oo.

In short, it removes Masako Holley as an owner of the zewhb.java file. However, the relation itself stays, and any other subject entities playing the owner role will continue to do so.

The isa object-ownership statement is omitted because we are not deleting the object-ownership relation itself, but rather a specific player of its owner role.

Attributes

Attributes can be owned by other types. A delete query can remove the attribute itself or remove the ownership of it (and leave the attribute).

Attributes are immutable. Rather than changing the value of an owned attribute, the ownership of it is replaced with the ownership of a new/different attribute.

Instances

Use a match clause followed by the delete keyword and a pattern containing an isa statement to remove an attribute from a database.

match
  $fn isa full-name;
  $fn “Bob”;
delete
  $fn isa full-name;

The above example finds the full-name attribute whose value is Bob and deletes it. As well as all ownerships of this attribute by any entities, relations, or other attributes.

Ownership

TypeDB allows multiple instances to share the same attribute, so it is more common to remove the ownership of an attribute rather than the attribute itself.

Use a match clause followed by the delete keyword and a pattern to remove the ownership of an attribute.

match
  $o isa object, has path $fp;
  $fp like "(logs/.*)";
delete
  $o has $fp;

The above query finds all object entities that have a path attribute whose value matches a regular expression (logs/.*). It then removes their ownership of any matching path attributes. However, the attributes themselves are not removed.

Even a slight alteration of a delete clause can produce a very different result. Be careful not to delete the wrong data accidentally. See the examples below.

The isa object statement in the query above is omitted because we are not deleting the object entities but rather their ownership of path attributes.

For example, the delete $o isa object, has $fp; clause with a match clause above deletes all matched objects $o. Thus, it deletes all their ownerships over any attributes, not only $fp.

We do not include path in the delete clause because it’s not needed for ownership deletion. The type of $fp should be specified in the match clause if it’s important. In this case, it is specified as path already.

For example, the delete $o has path $fp; clause with a match clause above produces an error.

Finally, we can delete the attributes themselves, thus deleting ownership over any of them by all instances of all types.

For example, the delete $fp isa path; clause with a match clause above deletes all matched path attributes, thus deleting all ownerships of these attributes from every owner of any type.