Version: 1.0 RC1 (Latest)

Query variables

For simplicity, most examples have hardcoded values in queries. Although that is fine for understanding and prototyping, it is not fine for production applications. For oh god so many reasons:

Your application becomes vulnerable to GraphQL injections. Any user input you miss to sanitize is a hazard.
Your application has to dynamically build each query with string interpolation.
The database receives a bunch of different queries which are just different flavors of the same query, but can't cache them efficiently because of their apparent difference.

The best practice is thus to use variables for all values that might change over different query runs. This is especially relevant when using filters.

Display database setup

This page assumes your database contains Book and Person collections and some documents in them:

Database schema
type Person {
  name: String!
  authoredBooks: [Book]
}

type Company {
  name: String!
  sells: [Book]
}

type Book {
  title: String!
  genre: String
  plot: String
  rating: Float
  author: Person
  seller: Company
}

Documents setup
mutation {
  c1:add_Company(input: {
    name: "The Indipendent Hipster Bookshop"
  }) { _docID name }
  c2:add_Company(input: {
    name: "The World-Destroying Large Chain"
  }) { _docID name }

  a1:add_Person(input: {
    name: "George Orwell"
  }) { _docID name }
  a2:add_Person(input: {
    name: "William Golding"
  }) { _docID name }
  a3:add_Person(input: {
    name: "David Foster Wallace"
  }) { _docID name }
  a4:add_Person(input: {
    name: "Victor Hugo"
  }) { _docID name }

  b11:add_Book(input: {
    title: "1984",
    genre: "Fiction",
    plot: "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
    rating: 4.20,
    _authorID: "bae-f630242e-3faf-525e-864c-422e09b00667",
    _sellerID: "bae-e2120437-8282-5e59-9e02-e98d82f73cc3"
  }) { _docID title }
  b12:add_Book(input: {
    title: "Down and Out in Paris and London",
    genre: "Biography",
    plot: "The adventures of a penniless British writer among the down-and-outs of two great cities.",
    rating: 4.09,
    _authorID: "bae-f630242e-3faf-525e-864c-422e09b00667",
    _sellerID: "bae-e2120437-8282-5e59-9e02-e98d82f73cc3"
  }) { _docID title }
  b21:add_Book(input: {
    title: "Lord of the Flies",
    genre: "Fiction",
    plot: "At the dawn of the next world war, a plane crashes on an uncharted island, stranding a group of schoolboys.",
    rating: 3.70,
    _authorID: "bae-db573e8d-2466-55b9-8da0-39003f530d44",
    _sellerID: "bae-f8755a60-c49f-510f-a435-c4ddfec82499"
  }) { _docID title }
  b31:add_Book(input: {
    title: "Infinite Jest",
    genre: "Fiction",
    plot: "A gargantuan, mind-altering tragi-comedy about the Pursuit of Happiness in America.",
    rating: 4.25
    _authorID: "bae-40b16347-07e0-5e97-85e0-8742eaba786e",
    _sellerID: "bae-e2120437-8282-5e59-9e02-e98d82f73cc3"
  }) { _docID title }
  b32:add_Book(input: {
    title: "Consider the Lobster and Other Essays",
    genre: "Nonfiction",
    plot: "Do lobsters feel pain? Did Franz Kafka have a funny bone? What is John Updike's deal, anyway? And what happens when adult video starlets meet their fans in person? Essays that are also enthralling narrative adventures.",
    rating: 4.18,
    _authorID: "bae-40b16347-07e0-5e97-85e0-8742eaba786e",
    _sellerID: "bae-f8755a60-c49f-510f-a435-c4ddfec82499"
  }) { _docID title }
  b41:add_Book(input: {
    title: "Les Misérables",
    genre: "Fiction",
    plot: "Victor Hugo's tale of injustice, heroism and love follows the fortunes of Jean Valjean, an escaped convict determined to put his criminal past behind him.",
    rating: 4.21,
    _authorID: "bae-7f9e6642-03e3-5f62-b684-3d5555f46f7d",
    _sellerID: "bae-f8755a60-c49f-510f-a435-c4ddfec82499"
  }) { _docID title }
}

Use variables

Variables are identified by the dollar sign $. The path to using them has three steps:

Replace the value with the variable name (ex. $bookID)
Provide the variable and its type in the query constructor (ex. query ($title: String))
Provide the variable value in a separate JSON object

Query a document by ID
query ($bookID: [ID!]) {
  Book(docID: $bookID) {
    _docID
    title
    plot
    author { name }
  }
}

Variables
{
  "bookID": "bae-b99349d9-9419-52c3-9b53-7a9b28e0ea33"
}

Result
{
  "data": {
    "Book": [
      {
        "_docID": "bae-b99349d9-9419-52c3-9b53-7a9b28e0ea33",
        "author": {
          "name": "David Foster Wallace"
        },
        "plot": "A gargantuan, mind-altering tragi-comedy about the Pursuit of Happiness in America.",
        "title": "Infinite Jest"
      }
    ]
  }
}

Query a document with filters
query ($plot: String, $minRating: Float64) {
  Book(filter: {
    plot: { _like: $plot }, rating: { _geq: $minRating }
  }) {
    title
    plot
    author { name }
    rating
  }
}

Variables
{
  "plot": "%love%",
  "minRating": 3.8
}

Result
{
  "data": {
    "Book": [
      {
        "author": {
          "name": "Victor Hugo"
        },
        "plot": "Victor Hugo's tale of injustice, heroism and love follows the fortunes of Jean Valjean, an escaped convict determined to put his criminal past behind him.",
        "rating": 4.21,
        "title": "Les Misérables"
      }
    ]
  }
}

Optional and mandatory variables

By default, it is optional to provide a value to a variable for a given query. No value (i.e. null) is an allowed value. For example, omitting the value for bookID is valid, and results in all books being returned:

Query with optional variables
query ($plot: String, $minRating: Float64) {
  Book(filter: {
    plot: { _like: $plot }, rating: { _geq: $minRating }
  }) {
    title
    plot
    rating
  }
}

Variables (no value for plot)
{
  "minRating": 4.2
}

Result
{
  "data": {
    "Book": [
      {
        "plot": "Victor Hugo's tale of injustice, heroism and love follows the fortunes of Jean Valjean, an escaped convict determined to put his criminal past behind him.",
        "rating": 4.21,
        "title": "Les Misérables"
      },
      {
        "plot": "A gargantuan, mind-altering tragi-comedy about the Pursuit of Happiness in America.",
        "rating": 4.25,
        "title": "Infinite Jest"
      },
      {
        "plot": "A masterpiece of rebellion and imprisonment where war is peace, freedom is slavery, and Big Brother is watching.",
        "rating": 4.2,
        "title": "1984"
      }
    ]
  }
}

You can make it mandatory to provide a value to a variable by appending an exclamation mark ! to the type in the query constructor.

Query with mandatory $title variable
query ($title: String!, $minRating: Float64) {
  Book(filter: {
    title: { _like: $title }, rating: { _geq: $minRating }
  }) {
    title
    rating
  }
}

Default values

You can set a default value for a variable in its declaration:

Query with default value for $title variable
query ($title: String = "%%", $minRating: Float64) {
  Book(filter: {
    title: { _like: $title }, rating: { _geq: $minRating }
  }) {
    title
    rating
  }
}

Use variables​

Optional and mandatory variables​

Default values​

Use variables

Optional and mandatory variables

Default values