Using Variables in GraphQL

How to pass variables into a GraphQL query,

Some of the examples given on other pages have the search criteria embedded in the GraphQL query. Although this is a perfectly acceptable method it does have a number of limitations:

If the search criteria includes a string there is a need to escape the quotes that surround it when passing the query in a JSON encoded payload in a POST body. This can complicate the construction of the query string.
When using paging (using take/skip) it is be necessary to change the skip value to page through the results. Without variables this will involve reconstructing the query string each time to include the new skip value.
If you're using a list of IDs to retrieve (for example, a list of company numbers) then building the list into a query string can be complicated - especially given the need to escape the quotes around each string.

Variables allow the query string to remain static whilst the variables are passed separately.

For example, this query retrieves two companies:

query example1 {
  companies(where:{company_number:{in:["11266456","01777777"]}}){
    items{
      company_number
      company_name
      generated_rfa_rating
    }
  }
}

Here is the same query, but this time using a variable to represent a list of company numbers:

query example2WithVariables($complist: [String]) {
  companies(where:{company_number:{in: $complist}}){
    items{
      company_number
      company_name
      generated_rfa_rating
    }
  }
}

Note that no matter how long or short (or how it varies over time) the list of companies ($complist) is, the query always remains the same.

When posting the query to the GraphQL end point, the variables can be passed in as a separate attribute to the query. This will be the POST body:

{
    "query": "query example2($complist: [String]) {companies (where: {company_number: {in: $complist}}) {items {company_number company_name}}}",
    "variables": {"complist": ["11266456","01777777"]}
}

Note, because the query string does not now contain any quotes, there is no need for anything to be escaped. The list of companies can be passed unescaped as a standard JSON encoded string array.

To define a variable, simply include its name (always preceded with a $ sign) in the brackets after the operation name (in this case example2WithVariables). The variable name should be terminated with a colon (:) followed by its type.

Numbers are "Int", "Decimal", "Long" or "Float"
Strings are "String"
Booleans (true/false) are "Boolean"
Dates are "DateTime"
Arrays are specified by surrounding the type in square brackets (such as [Int])

Other non-scalar object values can also be specified as a type. To see what type a particular field is, see the "Schema Reference" in the GraphQL IDE interface. See Accessing the GraphQL API with a Browser for more information.

You can specify multiple variables in a query. Just define each variable you wish to use in the brackets and reference them in the query. For example:

query example2WithVariables($skip: Int $take: Int $complist: [String]) {
  companies(take: $take skip: $skip where:{company_number:{in: $complist}}){
    items{
      company_number
      company_name
      generated_rfa_rating
    }
  }
}

If you have any further questions, please reach out to our Support Team via Contact Us.