JSON Data Format

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 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"
     }
   ]
 }

You see that Dgraph responds with

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

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 refer to the same identifier, Dgraph creates only one node:

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

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" }
  }
}

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"
     }
   ]
 }

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

Language support

To set a string value for a specific language, 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"
     }
   ]
 }

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 ]
       }
     }
   ]
 }

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"
        }]
     }
   ]
 }

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"
    }
  }
}

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
     }
   ]
}

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
}

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

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

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"
      }
   ]
}

Handling arrays

To create a predicate as a list of string:

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

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"
  }
}

To remove multiple values:

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

To add a value:

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

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"
  }
}

Facets don’t contain type information but Dgraph tries to guess a type from the input. If the value of a facet can be parsed to a number, it is converted to either a float or an int. If it can be parsed as a Boolean, it is stored as a Boolean. If the value is a string, it is 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’s 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] .

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 that don’t have facets values are excluded from the facets map.

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

Above you see that there are 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
   }
}

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"
    }
  ]
}

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"
        ]
      }
    ]
  }
}

Reserved values

The string values uid(...), val(...) aren’t accepted.