Mutation Introduction

In the last exercise, you added some data into Dgraph. Adding or removing data in Dgraph is called a mutation. We have two types of standard formats for mutations: RDF (Resource Description Framework) N-Quad and JSON (JavaScript Object Notation). RDF is a widely used standard in Graph or Ontology systems.

In Dgraph the mutation operations consist of two patterns: blank UID reference or explicit UID reference.

This introduction is important for the coming exercises, many of the concepts presented here will be repeated in the next few chapters. (For example, Adding Data - mutating data and Exercise : Integrating existing data.)

Blank UID

In a mutation, any definition that doesn’t match the UID explicit reference format can be considered blank UID reference, also known as a blank node. The structure of a blank node consists of:

underline + a colon + unique name (identifier)

For example, in the previous section you saw the blank nodes _:michael and _:amit. This is the proper blank node syntax. However, there will be cases where the parser will consider some typo as a blank node, but its use is not recommended. Examples below:

<_:uid43> or <_:uid4e030f>
<someTypoMistake>

Dgraph’s data export uses blank nodes of the first form presented.

In JSON, the blank node format is similar. The blank node is defined with the "uid" key of a JSON object:

{
  "uid": "_:diggy",
  "name": "diggy",
  "food": "pizza"
}

Blank nodes are covered in more detail in the mutation docs.

Explicit UID

To do a mutation for an existing node, you can refer to the node’s UID directly in the mutation. The syntax is simple:

<THE-UID> # or 
<0x4e030f> <somePredicate> "some new data" .

One way to know an existing node’s UID is to simply query for the indexed predicate, e.g:

{
  MyUser(func: eq(name, "Jack Torrance")) {
    uid
  }
}
Note

You should only reference existing UIDs. If you write a mutation with an unallocated UID, Dgraph will return an error. For new nodes, use blank nodes for Dgraph to allocate a new UID.

dgraph-icon