Query variables

GraphQL variables let you pass dynamic values to a query or mutation without changing the operation itself. In xDI, you define the variable structure in the metadata, then map input data to those variables in a mapping.

For a general introduction to GraphQL variables, see Variables in the GraphQL specification.

Error tolerance behaves differently when you use variables in mappings. For details, see Error tolerance with query variables.

Define variables in metadata

In a GraphQL query, variables are parameters identified with a $ prefix. For example, the $id variable in the following query represents a dynamic value:

query ($id: ID) {
  book(id: $id) {
    id
    title
    author
  }
}

To define variables in metadata:

  1. In the metadata editor, right-click a Query node and select New > Variables.

  2. Right-click the Variables node and create a JSON Root Object.

  3. Add fields to the JSON root object. Each field name must match a variable name in your query, without the $ prefix.

  4. Set each field’s type to match the corresponding GraphQL type. See Variable types reference for the mapping between GraphQL types and JSON field types.

The following structure shows what the variables node looks like for a query that takes a single id variable of type ID:

Query node (GetBook)
└── Variables
    └── root (JSON Root Object)
        └── id (string)

Required and optional variables

GraphQL distinguishes between required and optional variables:

  • $var: Type declares an optional variable. It can be null.

  • $var: Type! declares a required variable. It must have a value.

When you define variables in metadata, the structure is the same for both. The GraphQL server enforces the constraint when it receives the query with its variables.

For example, in the following query, in0 is optional and in1 is required:

query ($in0: Int, $in1: Int!) {
  scalarArgument(in0: $in0, in1: $in1) {
    out0
    out1
  }
}

Variable types reference

The following table maps GraphQL variable types to the types you use when defining fields in the Variables node.

GraphQL type Variables field type Example value

Int

number

42

Float

number

3.14

String

string

"hello"

Boolean

boolean

true

ID

string

"abc123"

[Type] (array)

array

[1, 2, 3]

Input object

object (with child fields)

{"title": "My Book", "author": "Alice"}

Object variables

For GraphQL input objects, create a nested JSON object in the Variables node with child fields that match the properties of the object. For example, the following mutation takes a BookInput object:

mutation newBook($book: BookInput) {
  upsertBook(book: $book) {
    id
    title
    author
  }
}

The variables node structure is:

Variables
└── root (JSON Root Object)
    └── book (object)
        ├── title (string)
        ├── author (string)
        └── id (string)

Array variables

For GraphQL list types, create a JSON array in the Variables node. For example, for a mutation that takes a list of integers:

mutation ($newList: [Int]) {
  setList(newList: $newList)
}

The variables node structure is:

Variables
└── root (JSON Root Object)
    └── newList (array)
        └── item (number)

Nested object variables

You can combine objects, arrays, and scalars to represent complex input types. For example:

mutation ($newObject: RootObjectInput) {
  writeObject(newObject: $newObject) {
    id
    string
    boolean
    subObject {
      id
      int
      float
    }
  }
}

The variables node structure is:

Variables
└── root (JSON Root Object)
    └── newObject (object)
        ├── id (string)
        ├── string (string)
        ├── boolean (boolean)
        └── subObject (object)
            ├── id (string)
            ├── int (number)
            └── float (number)

Use variables in mappings

After you define variables in the metadata, use them in mappings to pass data dynamically.

Mapping pattern

The general mapping pattern with variables is:

Source datastore
    ↓ (map fields to variable fields)
Variables node
    ↓ (query executes with variable values)
Response node
    ↓ (map response fields)
Target datastore

Each row in the source datastore triggers a separate query execution with the corresponding variable values.

Map inputs to variables

To use variables in a mapping:

  1. Drag the Query node from your GraphQL metadata into a mapping.

  2. Add a source datastore, for example a database table, that contains the input values.

  3. Map fields from the source datastore to the corresponding fields in the Variables node.

  4. Map the response data to a target datastore.

For example, if you have a table of book IDs and want to query details for each book:

  • The source table has a BOOK_ID column.

  • Map BOOK_ID to Variables/root/id.

  • Each row in the source table triggers a GetBook query with a different ID.

  • Map the response fields (title, author) to the target table.

Reuse variables as outputs

Variable values can also be mapped to output datastores. This approach is useful for:

  • Creating audit trails that record which inputs produced which outputs

  • Debugging mapping behavior by echoing variable values alongside response data

  • Joining input data with response data in the target

Variables work similarly to HTTP REST request parameters. Both let you map data from datastores as inputs to control API behavior dynamically. The main difference is that GraphQL variables use a JSON structure, while REST parameters are individual fields.