TypeDB Fundamentals Lecture Series: from Nov 16 to Jan 9

Delete query

A Delete query removes data from a TypeDB database. You can delete an instance of a type, ownership of an attribute, or a role player reference of a relation.

Delete queries can be used only in write transactions.

Behavior

A Delete query deletes concepts, ownerships, and role player references from a database.

After matching existing data with a match clause, use a delete clause with another TypeQL pattern to specify exact data to delete.

A delete clause is executed once per every result of a preceding match clause. In particular, if there is no match in a database for a match clause of a delete query, then there will be no deletions.

A Delete query returns a Promise of an empty response.

Syntax

A Delete query consists of a match clause and a delete clause.

Delete queries are written in TypeQL with the following syntax:

match <pattern>
delete <pattern>

A delete clause pattern uses variables from a preceding match clause pattern.

Match clause

A match clause is mandatory in a Delete query. You can use a declarative and composable TypeQL pattern in a match clause and TypeDB will find data that matches specified pattern.

For more information on a match clause, see the Match clause description on the Queries page.

For more information on patterns used in a match clause, see the Pattern syntax section.

Delete clause

A delete clause is used in a Delete query to specify exact data to remove from a database. deleted data should be matched first in a preceding match clause.

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

  • Disjunction

  • Negation

  • is keyword

This clause is executed exactly once for every result matched by a preceding match clause of the same query.

A delete clause returns a Promise of an empty response.

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

Deleting instances

To delete an entity, attribute, or relation, you need to match them with a match clause and then use the following pattern in a delete clause of the same query:

Deleting an instance of data pattern syntax
<variable> isa <type>;

Where <variable> (e.g., $x) — a query variable of a matched instance to delete; <type> (e.g., person) — type or supertype of the deleted instance.

With this pattern, the instance of data is removed completely, including all roles played and attributes owned by the deleted instance.

Deleting an attribute will result in all owners of such attribute to lose ownership of it. Deleting a relation will result in all instances that played roles in the relation to no longer play that role in the deleted relation.

See an example of deleting instances of data below.

Deleting ownerships

To delete an ownership of an attribute, match both the attribute and its owner and then use the following pattern in a delete clause of the same query:

Deleting an ownership pattern syntax
<owner-variable> has <attribute-variable>;

With this pattern, an attribute itself is not removed, but rather an ownership of that attribute by that owner is removed.

Attributes are immutable. Rather than changing the value of an owned attribute, you can delete an ownership of it and replace with an ownership of another attribute with different value.

See an example of deleting ownership of an attribute below.

Orphaned attributes

If an attribute is not owned by any other instance, then such an attribute is called orphaned. Orphaned attributes are not deleted automatically, but quite often, they are You can easily delete all of them from a database with the following query. .Deleting orphaned attributes

match
$a isa attribute;
not {$x has $a;};
delete
$a isa attribute;

Deleting role players from a relation

To delete a role player from a relation, match both the relation and the instance of data that plays a role and then use the following pattern in a delete clause of the same query:

Deleting a role player from a relation pattern syntax
<relation-variable> (<role>:<instance-variable>);

Where <relation-variable> — a query variable of the relation to modify; <role> — an optional specification of a role of a role player to remove; <instance-variable> — a query variable of a role player instance.

With this pattern, an instance that plays a role in a relation is not removed, but rather the information of that role player is removed from a relation.

We can omit the role in a pattern if its unambiguous which role the referenced instance can play in the relation.

Existence of a relation often implies the existence of all of its role players. Deleting a role player reference from a relation can create an incomplete data state. Like a marriage relation with only one known spouse.

Since relations must have at least one role player to exist, all relations without a role player are implicitly deleted at commit.

See an example of deleting role players from a relation.

Examples

Use the IAM schema and sample data for the following examples.

Deleting an instance of data

Instances of data (entities, attributes, and relations) can be deleted by matching them first, then using a delete clause with the isa pattern.

Deleting example
match
$p isa person, has email "john.parkson@gmail.com";
delete
$p isa person;

In the above query, match clause finds a person entity that has the email attribute with the value of john.parkson@gmail.com. Then, it removes the matched entity from a database.

Deleting with the use of a supertype

One can delete an instance by using not only its exact type in the delete clause pattern, but also any of its supertypes. It can be especially useful with matching using inheritance polymorphism.

Deleting an attribute by its supertype
match
$fn == "Bob";
delete
$fn isa attribute;

In the above example we are matching all concepts of any type with the value of Bob. Since only attributes can have a value, all matched concepts are instances of attribute types. So we can delete all of them be using their common supertype, in this case — root type attribute.

Attributes

A Delete query can remove an attribute itself or delete an ownership of it from another instance.

Deleting an attribute

To delete an attribute, match it in a database and then use a delete clause with an isa pattern:

Deleting an attribute
match
$fn isa full-name;
$fn == "Bob";
delete
$fn isa full-name;

The above example matches the attribute by its type (full-name) and value (Bob) and assigns it a query variable ($fn). Then it deletes the matched attribute.

Deleting ownership

To delete ownership of an attribute by any instance, match both the owner and the attribute and then use a delete clause with a has pattern:

Deleting ownership
match
$p has full-name $fn;
$fn == "Bob";
delete
$p has $fn;

The above query finds all person entities ($p) that have a full-name attribute ($fn) whose value is equal to Bob. For every matched pair of $p and $fn it deletes an ownership of $fn by $p.

We are not using isa person statement in the delete clause above because we don’t want $p to be deleted, only its ownership of $fn.

Relations

We can delete a relation or a role player reference from a relation.

Deleting a relation

To delete a relation, match it in a database and then use a delete clause with an isa pattern:

Deleting a relation
match
$p isa subject, has full-name "Pearle Goodman";
$pe (subject: $p) isa permission;
delete
$pe isa permission;

The above query does the following:

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

  2. Finds all permission relations ($pe) relating the subject entity $p (as the subject role).

  3. Deletes all matched permissions $pe.

In short, it removes all permissions for Pearle Goodman.

We didn’t specify all roles of a permission relation, e.g., the object role.

Deleting a role player

To delete a role player reference from a relation, match it in a database and then use a delete clause without an isa pattern, specifying just the relation variable and the role player reference in parentheses:

Deleting a role player reference
match
$p isa subject, has full-name "Pearle Goodman";
$pe (subject: $p) isa permission;
delete
$pe ($p);

The above query does the following:

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

  2. Finds all permission relations ($pe) relating the subject entity $p (as the subject role).

  3. From every matched relation $pe deletes the reference to the $p.

In short, it removes Pearle Goodman as the subject from all of its permission relations. However, the relations are not deleted, and any other role player references are left intact.

We are not using isa permission statement in the delete clause above because we don’t want any $pe relations to be deleted, only modified by deleting a role player reference from them.

Provide Feedback