We’re overhauling Dgraph’s docs to make them clearer and more approachable. If you notice any issues during this transition or have suggestions, please let us know.
Dgraph Query Language (DQL) is Dgraph’s proprietary language to add, modify, delete and fetch data.
Fetching data is done through DQL Queries. Adding, modifying, or deleting data is done through DQL Mutations.
This overview explains the structure of DQL Mutations and provides links to the appropriate DQL reference documentation.
DQL mutations support JSON or RDF format.
In DQL, you add data using a set mutation, identified by the set
keyword.
A delete mutation, identified by the delete
keyword, removes triples
from the store.
For example, if the store contained the following:
Then, the following delete mutation deletes the specified erroneous data, and removes it from any indexes:
In many cases you need to delete multiple types of data for a predicate. For a
particular node N
, all data for predicate P
(and all corresponding indexing)
is removed with the pattern S P *
.
The pattern S * *
deletes all the known edges out of a node, any reverse edges
corresponding to the removed edges, and any indexing for the removed data.
For mutations that fit the S * *
pattern, only predicates that are among the
types associated with a given node (using dgraph.type
) are deleted. Any
predicates that don’t match one of the node’s types remains after an S * *
delete mutation.
If the node S
in the delete pattern S * *
has only a few predicates with a
type defined by dgraph.type
, then only those triples with typed predicates are
deleted. A node that contains un-typed predicates still exists after a S * *
delete mutation.
The patterns * P O
and * * O
aren’t supported because it’s inefficient to
store and find all the incoming edges.
Deleting the value of a non-list predicate (i.e a 1-to-1 relationship) can be done in two ways.
For language-tagged values, the following special syntax is supported:
In this example, the value of the name
field that’s tagged with the language
tag es
is deleted. Other tagged values are left untouched.
Upsert is an operation where:
The upsert block allows performing queries and mutations in a single request. The upsert block contains one query block and mutation blocks.
The structure of the upsert block is as follows:
Execution of an upsert block also returns the response of the query executed on the state of the database before mutation was executed. To get the latest result, you have to execute another query after the transaction is committed.
Variables defined in the query block can be used in the mutation blocks using the UID and val functions.
The upsert block also allows specifying conditional mutation blocks using an
@if
directive. The mutation is executed only when the specified condition is
true. If the condition is false, the mutation is silently ignored. The general
structure of Conditional Upsert looks like as follows:
The @if
directive accepts a condition on variables defined in the query block
and can be connected using AND
, OR
and NOT
.
Let’s say in our previous example, we know the company1
has less than 100
employees. For safety, we want the mutation to execute only when the variable
v
stores less than 100 but greater than 50 UIDs in it. This can be achieved as
follows:
We can achieve the same result using json
dataset as follows:
We’re overhauling Dgraph’s docs to make them clearer and more approachable. If you notice any issues during this transition or have suggestions, please let us know.
Dgraph Query Language (DQL) is Dgraph’s proprietary language to add, modify, delete and fetch data.
Fetching data is done through DQL Queries. Adding, modifying, or deleting data is done through DQL Mutations.
This overview explains the structure of DQL Mutations and provides links to the appropriate DQL reference documentation.
DQL mutations support JSON or RDF format.
In DQL, you add data using a set mutation, identified by the set
keyword.
A delete mutation, identified by the delete
keyword, removes triples
from the store.
For example, if the store contained the following:
Then, the following delete mutation deletes the specified erroneous data, and removes it from any indexes:
In many cases you need to delete multiple types of data for a predicate. For a
particular node N
, all data for predicate P
(and all corresponding indexing)
is removed with the pattern S P *
.
The pattern S * *
deletes all the known edges out of a node, any reverse edges
corresponding to the removed edges, and any indexing for the removed data.
For mutations that fit the S * *
pattern, only predicates that are among the
types associated with a given node (using dgraph.type
) are deleted. Any
predicates that don’t match one of the node’s types remains after an S * *
delete mutation.
If the node S
in the delete pattern S * *
has only a few predicates with a
type defined by dgraph.type
, then only those triples with typed predicates are
deleted. A node that contains un-typed predicates still exists after a S * *
delete mutation.
The patterns * P O
and * * O
aren’t supported because it’s inefficient to
store and find all the incoming edges.
Deleting the value of a non-list predicate (i.e a 1-to-1 relationship) can be done in two ways.
For language-tagged values, the following special syntax is supported:
In this example, the value of the name
field that’s tagged with the language
tag es
is deleted. Other tagged values are left untouched.
Upsert is an operation where:
The upsert block allows performing queries and mutations in a single request. The upsert block contains one query block and mutation blocks.
The structure of the upsert block is as follows:
Execution of an upsert block also returns the response of the query executed on the state of the database before mutation was executed. To get the latest result, you have to execute another query after the transaction is committed.
Variables defined in the query block can be used in the mutation blocks using the UID and val functions.
The upsert block also allows specifying conditional mutation blocks using an
@if
directive. The mutation is executed only when the specified condition is
true. If the condition is false, the mutation is silently ignored. The general
structure of Conditional Upsert looks like as follows:
The @if
directive accepts a condition on variables defined in the query block
and can be connected using AND
, OR
and NOT
.
Let’s say in our previous example, we know the company1
has less than 100
employees. For safety, we want the mutation to execute only when the variable
v
stores less than 100 but greater than 50 UIDs in it. This can be achieved as
follows:
We can achieve the same result using json
dataset as follows: