GraphQL Variables

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.

Syntax Examples (using default values):

• query title($name: string = "Bauman") { ... }
• query title($age: int = "95") { ... }
• query title($uids: string = "0x1") { ... }
• query title($uids: string = "[0x1, 0x2, 0x3]") { ... }. The value of the variable is a quoted array.

Variables can be defined and used in queries which helps in query reuse and avoids costly string building in clients at runtime by passing a separate variable map. A variable starts with a $ symbol. For HTTP requests with GraphQL Variables, we must use Content-Type: application/json header and pass data with a JSON object containing query and variables.

curl -H "Content-Type: application/json" localhost:8080/query -XPOST -d $'{
  "query": "query test($a: string) { test(func: eq(name, $a)) { \n uid \n name \n } }",
  "variables": { "$a": "Alice" }
}' | python -m json.tool | less

$a: "5",
$b: "10",
$name: "Steven Spielberg"

query {
  test($a: int, $b: int, $name: string) {
    me(func: allofterms(name@en, $name)) {
      name@en
      director.film (first: $a, offset: $b) {
        name @en genre(first: $a) { name@en }
      }
    }
  }
}

• Variables can have default values. In the example below, $a has a default value of 2. Since the value for $a isn’t provided in the variable map, $a takes on the default value.
• Variables whose type is suffixed with a ! can’t have a default value but must have a value as part of the variables map.
• The value of the variable must be parsable to the given type, if not, an error is thrown.
• The variable types that are supported as of now are: int, float, bool and string.
• Any variable that’s being used must be declared in the named query clause in the beginning.

$b: "10",
$name: "Steven Spielberg"

query {
  test($a: int = 2, $b: int!, $name: string) {
    me(func: allofterms(name@en, $name)) {
      director.film (first: $a, offset: $b) { genre(first: $a) { name@en } }
    }
  }
}

You can also use array with GraphQL Variables.

$b: "10",
$aName: "Steven Spielberg",
$bName: "Quentin Tarantino"

query {
  test($a: int = 2, $b: int!, $aName: string, $bName: string) {
    me(func: eq(name@en, [$aName, $bName])) {
      director.film (first: $a, offset: $b) { genre(first: $a) { name@en } }
    }
  }
}

We also support variable substitution in facets.

$name: "Alice",
$IsClose: "true"

query {
  test($name: string = "Alice", $IsClose: string = "true") {
    data(func: eq(name, $name)) {
      friend @facets(eq(close, $IsClose)) { name }
      colleague : friend @facets(eq(close, false)) { name }
    }
  }
}

If you want to input a list of UIDs as a GraphQL variable value, you can have the variable as string type and have the value surrounded by square brackets like ["13", "14"].