Analytics

ShopifyQL is the query language behind Shopify Analytics. The metric cards, dashboards, and reports in the Shopify admin run on ShopifyQL. Your app reads analytics data with ShopifyQL. You build on ShopifyQL with four building blocks: model, query, embed, and enrich.

For example, an email marketing app uses all four building blocks:

• Model your app's data: add a campaign_source metafield to orders and send an email_sent App Event. Merchants query the campaign_source metafield and the email_sent event beside store data.
• Query the data with ShopifyQL through the GraphQL Admin API: run a query like FROM app_events SHOW emails_sent GROUP BY app_name.
• Embed the results with a web component: show the query results on the app's dashboard with the <s-shopifyql-metric-card> metric card.
• Enrich the charts with an annotation: mark a date, such as the day a campaign goes live, and the store's charts show the marker beside the metric's change.

Merchants query your app's data in Shopify Analytics, and you don't need a separate analytics store. The data comes from metafields on Shopify records such as orders and customers, the metaobjects that the metafields reference, or App Events that your app sends.

Anchor to MetafieldsMetafields

Mark a metafield definition as analytics-queryable, and ShopifyQL exposes the metafield's values as a dimension beside store data. For example, add a campaign_source metafield to an order or a subscription_status metafield to a customer. Merchants can then group, filter, and chart reports on the metafield. Shopify already stores the metafield values.

Anchor to Category metafieldsCategory metafields

When a merchant assigns a product category, Shopify adds category metafields for that category's attributes, such as color, size, and material. Category metafields are queryable in ShopifyQL under the shopify namespace with no setup, for example product.metafields.shopify.material. Results show the label of the taxonomy attribute value that the merchant selected, such as Organic cotton. Results don't show a metaobject ID. Use CONTAINS to filter on a category metafield, because a product can have more than one value for an attribute. Wrap attribute names that contain a hyphen in double quotes, like product.metafields.shopify."color-pattern".

Anchor to Metaobject fieldsMetaobject fields

When a product, product variant, customer, or order metafield references a metaobject, you can query that metaobject's fields through the metafield by adding the field key to the end. For example, if a product's custom.designer metafield points to a Designer metaobject, then product.metafields.custom.designer.country is a dimension. If the metafield references a list of metaobjects, then the metaobject field returns a list. Use CONTAINS to filter a list field.

To make a metaobject's fields queryable, enable the analyticsQueryable capability on its metaobject definition with the metaobjectDefinitionCreate or metaobjectDefinitionUpdate mutation, available in GraphQL Admin API version 2027-01 and later. The definition must include at least one field of a type that analytics supports, such as text, number, or date. Query the capability's eligible field to check whether a definition qualifies. Merchants can also turn on the capability in the Shopify admin with the Filter or group data in Analytics setting on the metaobject definition.

Queries follow the reference from the record to the metaobject. You can't start from a metaobject and query the records that point to it.

Use metafield capabilities

Enable the analytics-queryable capability and see which metafield owners and types are eligible.

App Events makes your app's events queryable in Shopify Analytics. Declare your events and send the events through the App Events API. Merchants then query the events in ShopifyQL. With App Events in Analytics, one query can compare the same event across every installed app.

App Events

Declare and send your app's events for merchants to query in Shopify Analytics.

Your app reads analytics data by running ShopifyQL through the GraphQL Admin API with the shopifyqlQuery field. Write a query once and run it in the Shopify admin or with the Python SDK. The ShopifyQL reference lists each metric and dimension with its type and examples. Developers and AI tools write valid queries from the reference.

Query with ShopifyQL

The three ways to run ShopifyQL, with setup and examples.

ShopifyQL syntax reference

The full ShopifyQL language: keywords, functions, and examples.

Use analytics web components to show the Shopify admin's charts to app users in your app. Each component runs a ShopifyQL query and handles chart rendering, currency formatting, and locale formatting for your app.

Analytics web components

Component reference, required scripts, and access setup.

An annotation is a dated note that explains why a metric moved. Shopify records your app as the annotation's creator in the createdByApp field. A loyalty app can mark the day a program launched, an email app can mark a campaign, and a subscription app can mark a pricing change. Create annotations with the analyticsAnnotationCreate mutation on the GraphQL Admin API, read them with analyticsAnnotations, and overlay them on a chart in ShopifyQL with ANNOTATE.

A metric target is a goal for a metric, such as total sales for the quarter. Merchants track progress against the goal in reports and dashboards. Create targets with the analyticsTargetCreate mutation on the GraphQL Admin API, read them with analyticsTargets, and compare against them in ShopifyQL with COMPARE TO TARGETS.

Annotations

Create, read, and manage annotations through the GraphQL Admin API.

Metric targets

Create and read metric targets through the GraphQL Admin API.

In the campaign dashboard tutorial series, you build a campaign dashboard that uses all four building blocks.

Campaign dashboard tutorial series

Start with part one. Store each campaign as a metaobject entry, and query the campaign's sales with ShopifyQL.