JSON Mutation Format

Dgraph supports Mutations in JSON or RDF format. When using JSON format Dgraph creates nodes and relationships from the JSON structure and assigns UIDs to nodes.

Specifying node UIDs

For example, if you run this mutation:

 {
   "set": [
     {
      "name": "diggy",
      "dgraph.type": "Mascot"
     }
   ]
 }  
Copy

You will see that Dgraph responds with

{
  "data": {
    "code": "Success",
    "message": "Done",
    "queries": null,
    "uids": {
      "dg.3162278161.22055": "0xfffd8d72745f0650"
    }
  }Copy

Meaning that Dgraph has created one node from the JSON. It has used the identifier dg.3162278161.22055 during the transaction. And the final UID value for this node is 0xfffd8d72745f0650.

You can control the identifier name by specifying a uid field in your JSON data and using the notation: "uid" : "_:<your-identifier>"

In this mutation, there are two JSON objects and because they are referring to the same identifier, Dgraph creates only one node:

   {
   "set": [
     {
      "uid": "_:diggy",
      "name": "diggy",
      "dgraph.type": "Mascot"
     },
     {
      "uid": "_:diggy",
      "specie": "badger"
     }
   ]
 }  
Copy

When you run this mutation, you can see that Dgraph returns the UID of the node that was created with the diggy identifier:

{
  "data": {
    "code": "Success",
    "message": "Done",
    "queries": null,
    "uids": {
      "diggy": "0xfffd8d72745f0691"
    }Copy

Note that the specie field is added to the node already created with name and dgraph.type information.

Referencing existing nodes

You can use the "uid" field to reference an existing node. To do so, you must specify the UID value of the node.

For example:

   {
   "set": [
     {
      "uid": "0xfffd8d72745f0650",
      "specie": "badger"
     }
   ]
 }  
Copy

Adds the specie information to the node that was created earlier.

Language support

To set a string value for a specific lnguage, append the language tag to the field name. In case, specie predicate has the @lang directive, the JSON mutation

   {
   "set": [
     {
      "uid": "_:diggy",
      "name": "diggy",
      "dgraph.type": "Mascot",
      "specie@en" : "badger",
      "specie@fr" : "blaireau"
     }
   ]
 }  
Copy

Dgraph sets the specie string predicate in English and in French.

Geolocation support

Geo-location data must be specified using keys type and coordinates in the JSON document. The supported types are Point, Polygon, or MultiPolygon .

 {
   "set": [
     {
      "name": "diggy",
      "dgraph.type": "Mascot",
      "home" : {
          "type": "Point",
          "coordinates": [-122.475537, 37.769229 ]
       }
     }
   ]
 }    
Copy

Relationships

Relationships are simply created from the nested structure of JSON.

For example:

 {
   "set": [
     {
      "uid": "_:diggy",
      "name": "diggy",
      "dgraph.type": "Mascot",
      "food" : [
        {
          "uid":"_:f1",
          "name": "earthworms"
        },
        {
          "uid":"_:f2",
          "name": "apples"
        }]
     }
   ]
 }

Copy

This result in the creation of three nodes and the food predicate as a relationship.

{
  "data": {
    "code": "Success",
    "message": "Done",
    "queries": null,
    "uids": {
      "diggy": "0xfffd8d72745f06d7",
      "f1": "0xfffd8d72745f06d8",
      "f2": "0xfffd8d72745f06d9"
    }
    ...Copy

You can use references to existing nodes at any level of your nested JSON.

Deleting literal values

To delete node predicates, specify the UID of the node you are changing and set
the predicates to delete to the JSON value null.

For example, to remove the predicate name from node 0xfffd8d72745f0691 :

{
   "delete": [
     {
      "uid": "0xfffd8d72745f0691",
      "name": null
     }
   ]
}
Copy

Deleting relationship

A relationship can be defined with a cardinality of 1 or many (list). Setting a relationship to null removes all the relationships.

{
  "uid": "0xfffd8d72745f06d7",
  "food": null
}
Copy

To delete a single relationship in a list, you must specify the target node of the relationship.

{
   "delete": [
      {
      "uid": "0xfffd8d72745f06d7",
      "food": {
          "uid": "0xfffd8d72745f06d9"
        }
      }
   ]
}

Copy

deletes only one food relationship.

To delete all predicates of a given node:

• make sure the node has a dgraph.type predicate
• the type is defined in the Dgraph types schema
• run a delete mutation specifying only the uid field

{
   "delete": [
      {
        "uid": "0x123"
      }
   ]
}
Copy

Handling arrays

To create a predicate as a list of string:

{
   "set": [
    {
      "testList": [
        "Grape",
        "Apple",
        "Strawberry",
        "Banana",
        "watermelon"
      ]
    }
   ]
}
Copy

For example, if 0x06 is the UID of the node created.

To remove one value from the list:

{
  "delete": {
    "uid": "0x6", #UID of the list.
    "testList": "Apple"
  }
}
Copy

To remove multiple multiple values:

{
  "delete": {
    "uid": "0x6",
    "testList": [
          "Strawberry",
          "Banana",
          "watermelon"
        ]
  }
}
Copy

To add a value:

{
   "uid": "0x6", #UID of the list.
   "testList": "Pineapple"
}
Copy

Adding Facets

Facets can be created by using the | character to separate the predicate and facet key in a JSON object field name. This is the same encoding schema used to show facets in query results. E.g.

{
  "name": "Carol",
  "name|initial": "C",
  "dgraph.type": "Person",
  "friend": {
    "name": "Daryl",
    "friend|close": "yes",
    "dgraph.type": "Person"
  }
}
Copy

Facets do not contain type information but Dgraph will try to guess a type from the input. If the value of a facet can be parsed to a number, it will be converted to either a float or an int. If it can be parsed as a Boolean, it will be stored as a Boolean. If the value is a string, it will be stored as a datetime if the string matches one of the time formats that Dgraph recognizes (YYYY, MM-YYYY, DD-MM-YYYY, RFC339, etc.) and as a double-quoted string otherwise. If you do not want to risk the chance of your facet data being misinterpreted as a time value, it is best to store numeric data as either an int or a float.

Deleting Facets

To delete a Facet, overwrite it. When you run a mutation for the same entity without a Facet, the existing Facet is deleted automatically.

Facets in List

Schema:

<name>: string @index(exact).
<nickname>: [string] .
Copy

To create a List-type predicate you need to specify all value in a single list. Facets for all predicate values should be specified together. It is done in map format with index of predicate values inside list being map key and their respective facets value as map values. Predicate values which does not have facets values will be missing from facets map. E.g.

{
  "set": [
    {
      "uid": "_:Julian",
      "name": "Julian",
      "nickname": ["Jay-Jay", "Jules", "JB"],
      "nickname|kind": {
        "0": "first",
        "1": "official",
        "2": "CS-GO"
      }
    }
  ]
}
Copy

Above you see that we have three values ​​to enter the list with their respective facets. You can run this query to check the list with facets:

{
   q(func: eq(name,"Julian")) {
    uid
    nickname @facets
   }
}
Copy

Later, if you want to add more values ​​with facets, just do the same procedure, but this time instead of using Blank-node you must use the actual node’s UID.

{
  "set": [
    {
      "uid": "0x3",
      "nickname|kind": "Internet",
      "nickname": "@JJ"
    }
  ]
}
Copy

And the final result is:

{
  "data": {
    "q": [
      {
        "uid": "0x3",
        "nickname|kind": {
          "0": "first",
          "1": "Internet",
          "2": "official",
          "3": "CS-GO"
        },
        "nickname": [
          "Jay-Jay",
          "@JJ",
          "Jules",
          "JB"
        ]
      }
    ]
  }
}
Copy

Reserved values

The string values uid(...), val(...) are not accepted.