Function input and output
This guide introduces how data is input to and output from Shopify Functions.
How it works
Anchor link to section titled "How it works"Shopify Functions request an input against the schema of the specific Function API schema. The output is also defined by the same Function API schema. The output is a declarative object which represents operations for Shopify to execute.
Shopify passes input as JSON to your function using STDIN
, and your function writes output to Shopify using STDOUT
. Refer to the WebAssembly API for details.
You can specify what input your function needs using an input query. For example, the structure of the JSON in the input example matches the shape of the following query:
When you create a function, an input.graphql
file is generated at the root of your project directory. You can edit the query to request the exact data you need, which results in a more performant function. The query is executed against the specific Function input API, in the context of the current execution.
Input example
Anchor link to section titled "Input example"The following example shows an input that retrieves a customer's email along with the payment methods:
Each Function API specifies the shape of the function's output using an object with the name FunctionResult
. For example, there's a FunctionResult
definition for the Order Discount API.
If a function discounts an order by $50.00, then it could return the following output:
GraphQL schema
Anchor link to section titled "GraphQL schema"Each Function API has a GraphQL schema representation, which you can use to improve your development workflow. For example, a GraphQL schema can be used with:
- The VSCode GraphQL plugin
- Language-specific code generation tools, such as
graphql_client
for Rust
On creation, each function includes a copy of the GraphQL schema in the schema.graphql
file.
Generating the latest schema
Anchor link to section titled "Generating the latest schema"If you're using an unstable API version, then the GraphQL schema might have changed since you created the function or last generated the schema. If you change your target API version, then the Function API schema might have changed between versions.
To generate the latest GraphQL schema for your function, use the generate schema
command. This command outputs the latest schema based on your function's API type and version to stdout. Yuo can save the output to a file or pipe it into a code generation tool.
To overwrite your function's schema.graphql
file with a newly generated version, run the following command from your function directory:
Limitations
Anchor link to section titled "Limitations"The following limitations apply to input queries:
- The maximum size for an input query, excluding comments, is 3000 bytes.
- Metafields with values exceeding 1 kB in size will not be returned.
Function input queries can have a maximum calculated query cost of 30. The following table describes the input query field costs for functions:
Field Cost value Any field that returns a Metafield
object (For example,metafield
on aProduct
object.)3 Any field on a Metafield
object (For example,value
.)0 hasAnyTag
3 inAnyCollection
3 Other leaf nodes (For example, id
orsku
on aProductVariant
object.)1
- Learn how input queries and metafields work in Shopify Functions.
- Learn how to use variables in input queries with Shopify Functions.