Build your first query
ShopifyQL is Shopify's commerce analytics query language. Every store generates commerce data for each sale, order, and customer, and a ShopifyQL query turns that data into structured results you can chart, embed, or analyze. The same query language runs in the Shopify admin, the GraphQL Admin API, and the Python SDK.
This tutorial starts you in the Shopify admin, where you write a query against a real store and see the results render as you type, before you build anything. You'll learn the shape of the language here, then run the same query from the GraphQL Admin API or the Python SDK when you're ready to move it into code.
For the full ShopifyQL syntax and every dataset, metric, and dimension, refer to the ShopifyQL reference.
For the full ShopifyQL syntax and every dataset, metric, and dimension, refer to the ShopifyQL reference.
Anchor to What you'll learnWhat you'll learn
In this tutorial, you'll learn how to do the following:
- Open the ShopifyQL editor in the Shopify admin.
- Write a query and read its results.
- Shape the query with metrics, dimensions, and a visualization.
- Answer a bigger question with one query instead of several.
- Take the same query to the GraphQL Admin API or the Python SDK.
Anchor to RequirementsRequirements
- A Shopify store, and an account with permission to open the store's Analytics section. This access is set by your staff permissions.
- Store data to run a query against.
Anchor to Step 1: Open the ShopifyQL editorStep 1: Open the Shopify QL editor
The ShopifyQL editor is the analytics workspace in the Shopify admin, where you write a query and see its results. To open it, go to Analytics and select New exploration. You can also select Reports to see a list of default queries.

The editor has three parts:
-
The query: Where you type ShopifyQL, or where the editor writes it for you as you use the controls.
-
The controls: The metrics, dimensions, filters, and visualization pickers that write the query for you as you select them.
-
The results: The table or chart that the query returns, updated as you edit.
NoteYou can use the quick filters above the query to set the date range, comparison period, and currency.
Note:You can use the quick filters above the query to set the date range, comparison period, and currency.
Anchor to Step 2: Write a queryStep 2: Write a query
Type a ShopifyQL query directly into the editor. As you type, the editor validates the query and renders the results below as a table or chart. If the query is invalid, then the editor flags the problem so you can fix it before running.
Start with a query that returns daily sales for the last 7 days:
ShopifyQL
Every query has the same shape. FROM picks a dataset, SHOW lists the metrics and dimensions to return, and clauses such as TIMESERIES, SINCE, and ORDER BY shape the rest.
The validation you see here is the same check your app handles in code: a malformed query sent through the GraphQL Admin API returns a parse error instead of results.
The validation you see here is the same check your app handles in code: a malformed query sent through the GraphQL Admin API returns a parse error instead of results.
Anchor to Step 3: Shape the query with the controlsStep 3: Shape the query with the controls
In Step 2, you wrote the query by hand. The editor also works the other way. Its controls build the ShopifyQL for you as you pick what to measure and how to break it down. The metrics and dimensions you select become the query shown in the editor. The editor keeps the two in sync, so you can build a query by clicking, then read the ShopifyQL it generates to learn the syntax.
- Metrics are the values you measure, such as gross sales or orders. They become the columns of your results and map to the
SHOWclause. - Dimensions are the attributes you break metrics down by, such as sales channel or day. They become the rows of your results and map to clauses such as
GROUP BYandTIMESERIES. - Filters narrow the results to the rows you care about, and map to the
WHEREclause.
To watch the sync work, rebuild the Step 2 query with the controls. Choose Gross sales and Orders as your metrics, then break them down by Day over the last 7 days. The editor writes the same FROM sales SHOW gross_sales, orders TIMESERIES day query you typed by hand, so you can see each selection land in a clause.
If you'd rather describe the report in plain language, ask Sidekick, the AI assistant in the Shopify admin, for what you want, such as "gross sales by month for the last year". Sidekick drafts the ShopifyQL and runs it, so you can read the query it produced and adjust from there.
Anchor to Step 4: Choose a visualizationStep 4: Choose a visualization
The visualization control sets how the results are drawn and maps to the VISUALIZE clause. You can draw the same data different ways, depending on the question you're answering. For the sales and orders query you built, a combination chart plots gross_sales as bars and orders as a line on the same time axis, so you can read revenue and order count together.
Choosing that chart adds a VISUALIZE clause to the query, telling the editor to draw gross_sales as bars and orders as a line:
ShopifyQL

The visualization is a display choice in the editor. The underlying response is always the same set of typed columns and rows. That distinction matters when you move to code. A VISUALIZE clause doesn't change the response shape your app receives, so your app always renders the results itself.
To add context to a timeline, you can mark events such as product launches or app installs directly on the chart with ANNOTATE.
To add context to a timeline, you can mark events such as product launches or app installs directly on the chart with ANNOTATE.
Anchor to Step 5: Ask for more in one queryStep 5: Ask for more in one query
Some questions look like they need several queries, such as sales and traffic for the same days, or this month against last month. Ask for the whole answer in one query instead. One query returns rows that already line up, so you don't join, compare, or add up results yourself. When you move the query into an app, the app sends one request instead of several.
Anchor to Combine two schemasCombine two schemas
To read metrics from two schemas for the same days, list both schemas in FROM. This query returns daily sales and sessions on the same rows, so you don't send one query for sales and another for sessions:
ShopifyQL
ShopifyQL joins the schemas on the dimensions that they share. Every GROUP BY and TIMESERIES field must exist with the same name in each schema. For more information, refer to multi-fact queries.
Anchor to Compare two periodsCompare two periods
To compare this week with last week, add COMPARE TO and WITH PERCENT_CHANGE to the query. The result has the metric for both periods and the percent change between them, so you don't send a query for each week:
ShopifyQL
Anchor to Break down by a dimensionBreak down by a dimension
To get a value for each product, group by the product instead of sending a query for each one. To get only some products, filter them with WHERE and IN. Use one TIMESERIES query over the full date range instead of a query for each day or week. This query returns weekly gross sales for each product over the last 90 days:
ShopifyQL
ShopifyQL calculates gross_sales for each product and week, so your app doesn't pull order rows and add them up in code. A query without LIMIT returns at most 1,000 rows, and a breakdown by product and week grows fast. To keep the result under the cap and still get totals, refer to Don't page through the row cap for totals.
Anchor to Next stepsNext steps
You've learned the language by prototyping in the editor. Now take that same query into code, using the path that fits what you're building. To put analytics inside an app, run the query through the GraphQL Admin API and render the results in your own UI. To explore or export the data, run it from Python and work with the results as a DataFrame.