Site · API
Creating a GraphQL Query
Last updated 18 November 2026
There are two ways to create GraphQL queries on your Site. Developers typically write .graphql files in their local project and deploy them using the Insites CLI tool. You can also create queries directly in the admin, which is useful for quick additions or testing without a full deployment cycle.
Creating a Query in the Admin
- Navigate to API from the main menu.
- Select GraphQL.
- Select CREATE GRAPHQL.
- Fill out the form (see the field reference below).
- Select CREATE GRAPHQL to save.
Field Reference
| Input Label | Type | Required | Description |
|---|---|---|---|
| Display Name | Input Field | Yes | A descriptive display name for your query. This is what you see in the admin list view. |
| Name | Input Field | No | The system identifier, derived from the File Path. This is the name used when calling the query from Liquid templates. |
| File Path | Input Field | Yes | The file location for your .graphql file. Use the folder picker to select the module path. When you leave the Display Name field, the admin fills in this path for you from that name. |
| Body | Code Editor | Yes | The GraphQL query or mutation definition. Write your query using standard GraphQL syntax. |
Note
The Name field is generated from the File Path. This is the identifier you reference when calling the query from your Liquid templates.
Creating Queries via the CLI Tool
For most development work, you will create .graphql files in your local project directory:
app/graphql/for custom application queries- Inside your module directory for module-specific queries
Deploy your queries using the CLI tool:
- During development:
insites-cli sync <environment>watches for file changes and uploads them immediately. - For production:
insites-cli deploy <environment>packages and deploys your full codebase.
insites-cli sync stagingOnce deployed, your queries appear in the GraphQL section of the admin and can be called from Liquid templates.
Note
Queries created via the CLI tool and queries created in the admin both work the same way. The CLI tool is the recommended workflow for development, while the admin is convenient for quick changes.