Delete query

A Delete query is used to delete data from a database. You can delete a data instance, ownership of an attribute, or a role player reference of a relation. For a practical guide on how to send a Delete query to TypeDB, see the Delete query page of the TypeDB Manual.

Syntax

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

match <pattern>
delete <delete_pattern>

where <delete_pattern> is a pattern 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

A Delete query deletes the data instances, ownerships, and role player assignments specified in the delete clause. A match clause is mandatory in a Delete query: the match clause provides results for the variables in delete clause.

To delete a data instance, you need to use an isa statement in an insert clause.
To delete ownership of an attribute, use a has statement.
Role players can be deleted with a role assignment statement. See Delete role players.

Query execution

A delete clause is executed once per every result of a preceding match clause. Deleting data doesn’t affect the set of matched results from the match clause of the same query: all matching is done by the time of the first delete.

A Delete query is idempotent: deleting the same concept twice will not result in any further changes to the database.

Since version 2.22.0 of TypeDB a Delete query doesn’t fail (throw an error) if its delete clause tries to delete previously deleted or non-existent data.

Query response

A Delete query returns a Promise of an empty response.

Delete data instances

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

To delete an entity, attribute, or relation, match it in a match clause, then use the matched concept variable in an isa statement with the type or supertype of the data instance.

Deleting an attribute will result in all owners of the attribute to lose ownership of it:

Deleting an attribute

match
$email "admin@jp.com" isa email;
delete
$email isa email;

When a data instance is deleted, all assignments of roles played and attribute ownerships are also deleted. The relations, where the roles were played, and attribute, that were owned, stay in a database, unless deleted explicitly with an isa statement.

Deleting an entity

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 a relation will result in all instances that played roles in the relation to no longer play that role in the deleted relation.

Deleting a relation

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

The above query does the following:

Finds the subject entity ($p), with full-name attribute value of Pearle Goodman.
Finds all permission relations ($pe) relating the subject entity $p (as the subject role).
Deletes all matched permissions $pe.

In short, it removes all permissions for Pearle Goodman. Notice that we didn’t specify all roles of a permission relation, e.g., the object role.

Delete with type inheritance

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

A data instance can be deleted by using not only its exact type in a delete clause pattern, but also any of its supertypes. It can be especially useful in polymorphic queries.

Deleting an attribute by its supertype

match
$fn == "Bob";
delete
$fn isa attribute;

The above query matches and deletes all attributes with the value of Bob, regardless of their type.

Delete ownerships

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

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

Deleting ownership

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

The above query finds all data instances ($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 an isa / isa! statement in the delete clause above because we don’t want neither owner nor attribute to be deleted. Only ownership of one by another.

Orphaned attributes

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

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

Deleting orphaned attributes

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

Delete role players

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

To delete a role player from a relation, match both the relation and data instance that needs to stop playing a role in it, then use role assignment statement in the delete clause of the same query. For example:

Deleting a role player reference

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

The above query does the following:

Finds the person entity ($p), with the full-name attribute of the Pearle Goodman value.
Finds all permission relations ($pe) relating the $p (as the subject role).
From every matched relation $pe deletes the reference to the $p.

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

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

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

Existence of a relation often implies the existence of all 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 committing.

We are not using an isa / isa! statement in the delete clause because we don’t want any data instances to be deleted.

Learn more

Lesson 4.3: Deleting data

Learn more about deleting data from a database in TypeDB Academy.

Delete query

See how to send a Delete query to TypeDB.