Skip to main content

Use variables in input queries

Function input queries can be customized on each function owner using input query variables. This is helpful when using fields with arguments like inAnyCollection.

For example, consider the following input query:

without-input-query-variables.graphql

query Input {
cart {
lines {
id
merchandise {
... on ProductVariant {
id
product {
inExcludedCollection: inAnyCollection(ids: ["gid://shopify/Collection/1", "gid://shopify/Collection/2", "gid://shopify/Collection/3"])
inVIPCollection: inAnyCollection(ids: ["gid://shopify/Collection/4", "gid://shopify/Collection/5"])
}
}
}
}
}
}

This input query will only work on the shop where those collections are defined, limiting the function to single shop. Additionally, there's no way to update these collections without deploying a new version of the function with an updated input query, or to vary them when your function is used multiple times in a shop.

This guide will explain how to use input query variables to make these arguments configurable.

Anchor to RequirementsRequirements

Anchor to Step 1: Specify variables for your queryStep 1: Specify variables for your query

Replace field argument values with a variable with a matching type. In the case of the ids argument of inAnyCollection, the type is [ID!].

with-input-query-variables.graphql

query Input($excludedCollectionIds: [ID!], $vipCollectionIds: [ID!]) {
cart {
lines {
id
merchandise {
... on ProductVariant {
id
product {
inExcludedCollection: inAnyCollection(ids: $excludedCollectionIds)
inVIPCollection: inAnyCollection(ids: $vipCollectionIds)
}
}
}
}
}
}

Anchor to Step 2: Specify values for variablesStep 2: Specify values for variables

Input query variables are populated by reading a JSON metafield on the function owner. The structure of the metafield value must be such that each top level key corresponds to a variable name, and each value matches that variables type. To satisfy the query above, we need to set a metafield value like this:

{
"excludedCollectionIds": [
"gid://shopify/Collection/1",
"gid://shopify/Collection/2",
"gid://shopify/Collection/3"
],
"vipCollectionIds": [
"gid://shopify/Collection/4",
"gid://shopify/Collection/5"
]
}
Tip

For any variables which do not appear as top level keys in the metafield, a value of null will be used. Similarly, if the metafield is not set, all variables will use a value of null. If a variable is declared as required using the ! suffix, and a value of null is passed, function execution will fail.

The metafield will be read from the function owner at runtime to populate the values for these variables. You can set this metafield using the same techniques as you would for configuration you would access in the function. To illustrate our example, we'll use the metafieldsSet mutation:

set-metafield.graphql

mutation SetMetafield {
metafieldsSet(metafields: [
{
namespace: "$app:my-namespace",
key: "my-key",
ownerId: "OWNER_ID",
type: "json",
value: "{\"excludedCollectionIds\"=>[\"gid://shopify/Collection/1\", \"gid://shopify/Collection/2\", \"gid://shopify/Collection/3\"], \"vipCollectionIds\"=>[\"gid://shopify/Collection/4\", \"gid://shopify/Collection/5\"]}{\"selectedCollectionIds\":[\"gid://shopify/Collection/1\",\"gid://shopify/Collection/2\",\"gid://shopify/Collection/3\"]}"
}
]) {
metafields {
id
}
}
}
Caution

Ensure you set metafields on the function owner. For example, Discount API variables would be set on the discount, Checkout Validation API variables would be set on the validation, Cart Transform API variables would be set on the cart transform, and so on. Input query variables do not utilize metafields on the shop or app installation.

You should use a reserved prefix in your metafield namespace so that other apps can't use your metafields.

Anchor to Step 3: Specify which metafield to use for input queriesStep 3: Specify which metafield to use for input queries

To specify which metafield contains the input query variables, you need to set the values in the extensions.input.variables section of the function's configuration file:

shopify.extension.toml

[extensions.input.variables]
namespace = "$app:my-namespace"
key = "my-key"

If you're using a previous version of the configuration file that doesn't have an [[extensions]] section, then the configuration section for input query variables is called [input.variables].

Once this configuration has been deployed, your function will start loading that metafield at runtime to populate your input query variables.

Anchor to LimitationsLimitations

  • Only JSON type metafields are supported.
  • Metafields above the size limit won't be returned. The function should use separate metafields in these cases.
  • Input query variables will return errors for any GraphQL list variable with a value that exceeds 100 elements.

Anchor to Next stepsNext steps

Was this page helpful?