--- title: ShopifyQL description: >- ShopifyQL is a commerce analytics query language that helps you analyze and understand your Shopify data. api_version: 2026-07 source_url: html: 'https://shopify.dev/docs/api/shopifyql/latest' md: 'https://shopify.dev/docs/api/shopifyql/latest.md' api_name: shopifyql --- # ShopifyQL ShopifyQL is a query language for commerce. You write a query to ask a question about a store, like total sales last month, and get back a table you can optionally visualize. It's SQL-like, so if you've written a database query before, it'll feel familiar. We provide various schemas covering sales, orders, customers, marketing, inventory, payments, and more, so questions about your store map to a schema you can query. ## Getting started Start with a question about your store and write it as a query. Each example adds one clause to the previous one, building from a simple total to more advanced queries. ##### How much did I sell last month? [`FROM`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#from) picks the [`sales`](https://shopify.dev/docs/api/shopifyql/latest/schemas/sales_revenue/sales) schema, [`SHOW`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#show) picks the `total_sales` metric, and [`DURING`](https://shopify.dev/docs/api/shopifyql/latest/syntax/since-until-during) `last_month` sets the window. The result is a single total. ##### How are sales trending day to day? Add [`TIMESERIES`](https://shopify.dev/docs/api/shopifyql/latest/syntax/timeseries) `day` to turn that single total into a daily series, and set the window with [`SINCE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/since-until-during) and [`UNTIL`](https://shopify.dev/docs/api/shopifyql/latest/syntax/since-until-during). The result has one row per day, ready to plot as a line. ##### Which channels drive the most sales? Add [`GROUP BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/group-by) `sales_channel` to split the total by channel, then [`ORDER BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/order-by) `total_sales DESC` to rank them. Each channel comes back alongside its sales. ##### How do sales compare to the period before? Add [`COMPARE TO`](https://shopify.dev/docs/api/shopifyql/latest/syntax/compare-to) `previous_period` to put each month next to the one before it. Pair it with [`TIMESERIES`](https://shopify.dev/docs/api/shopifyql/latest/syntax/timeseries) `month` so the comparison lines up period by period. ##### Which marketing drives attributed sales? Add [`WITH`](https://shopify.dev/docs/api/shopifyql/latest/syntax/with) `LAST_CLICK_ATTRIBUTION` to credit sales to the channel that earned the last click before each order. The attributed total comes back as `total_sales__last_click`, which you can rank with [`ORDER BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/order-by). ## Total sales last month ```shopifyql FROM sales SHOW total_sales DURING last_month ``` ## Daily sales trend ```shopifyql FROM sales SHOW total_sales TIMESERIES day SINCE -30d UNTIL today ``` ## Sales by channel ```shopifyql FROM sales SHOW total_sales GROUP BY sales_channel DURING last_month ORDER BY total_sales DESC ``` ## Month-over-month sales ```shopifyql FROM sales SHOW total_sales TIMESERIES month SINCE -6m UNTIL today COMPARE TO previous_period ``` ## Attributed sales by channel ```shopifyql FROM sales SHOW total_sales GROUP BY referring_channel WITH LAST_CLICK_ATTRIBUTION DURING last_month ORDER BY total_sales__last_click DESC ``` [Tutorial - Build your first query with ShopifyQL](https://shopify.dev/docs/apps/build/shopifyql) *** ## Running Shopify​QL You write a query once and run the same query across the tools you already use. The query is identical everywhere, and only the call around it changes. | If you… | Use | | - | - | | Explore, visualize, save, or share reports with live data | [ShopifyQL editor](https://help.shopify.com/en/manual/reports-and-analytics/shopify-reports/report-types/shopifyql-editor) in the Shopify admin | | Build queries into an app backend or dashboard | [`shopifyqlQuery`](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyqlQuery) in the GraphQL Admin API | | Analyze or export data in scripts or notebooks | [Python SDK and CLI](https://shopify.dev/docs/apps/build/shopifyql/python-sdk-and-cli) | #### ShopifyQL editor ## ShopifyQL ```shopifyql FROM sales SHOW total_sales, orders TIMESERIES month SINCE -12m UNTIL today ``` The editor displays the results, which you can chart, save, or share as a report: | Month | Total sales | Orders | | - | - | - | | 2026-01-01 | 10000.00 | 25 | #### GraphQL Admin API ## Request ```graphql query RunShopifyQL { shopifyqlQuery( query: "FROM sales SHOW total_sales, orders TIMESERIES month SINCE -12m UNTIL today" ) { tableData { columns { name dataType displayName } rows } parseErrors } } ``` ## Response ```json { "data": { "shopifyqlQuery": { "tableData": { "columns": [ { "name": "month", "dataType": "MONTH_TIMESTAMP", "displayName": "Month" }, { "name": "total_sales", "dataType": "MONEY", "displayName": "Total sales" }, { "name": "orders", "dataType": "INTEGER", "displayName": "Orders" } ], "rows": [ { "month": "2026-01-01", "total_sales": "10000.00", "orders": 25 } ] }, "parseErrors": [] } } } ``` #### Python ## Request ```python from shopifyql import ShopifyQLClient client = ShopifyQLClient(shop="your-shop", access_token="shpat_...") df = client.query_pandas( "FROM sales SHOW total_sales, orders TIMESERIES month SINCE -12m UNTIL today" ) print(df) ``` ## Response ```text month total_sales orders 0 2026-01-01 10000.00 25 ``` *** ## Parts of a query Every ShopifyQL query comes down to two parts, the syntax you write and the schema you write it against. ### Syntax Syntax is the clauses you write and how you combine them. [`FROM`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#from) is required, and every query needs result selection through [`SHOW`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#show) or [`VISUALIZE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#visualize). Use `SHOW` to choose returned table columns. If you omit `SHOW`, use `VISUALIZE` to select the metric to render. The other clauses each shape the result, such as filtering rows with [`WHERE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/where) or grouping by a dimension with [`GROUP BY`](https://shopify.dev/docs/api/shopifyql/latest/syntax/group-by). [Reference - Explore ShopifyQL syntax](https://shopify.dev/docs/api/shopifyql/2026-07/syntax) ## ShopifyQL syntax ```shopifyql FROM sales SHOW total_sales WHERE sales_channel = 'Online Store' GROUP BY product_title DURING last_month ORDER BY total_sales DESC LIMIT 10 VISUALIZE total_sales TYPE horizontal_bar ``` ### Schemas A schema is a queryable table and the fields it exposes: the metrics you can measure and the dimensions you can break them down by. The schema you pick with [`FROM`](https://shopify.dev/docs/api/shopifyql/latest/syntax/from-and-show#from) decides which fields the rest of your query can use, so it's the first choice you make in any query. [Reference - Explore all schemas](https://shopify.dev/docs/api/shopifyql/2026-07/schemas) ## Sales schema fields ```shopifyql FROM sales SHOW total_sales, orders, average_order_value DURING last_month ``` *** ## Visualization and rendering In the [ShopifyQL editor](https://help.shopify.com/en/manual/reports-and-analytics/shopify-reports/report-types/shopifyql-editor), [`VISUALIZE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#visualize) sets the chart you see. Through the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql/latest/queries/shopifyqlQuery) or the [Python SDK and CLI](https://shopify.dev/docs/apps/build/shopifyql/python-sdk-and-cli), the same query returns table data, and your app renders the chart from the rows. Set a chart type with `TYPE`, like `line` or `horizontal_bar`, and ShopifyQL picks one for you if you leave it off. ShopifyQL supports chart types for comparisons, trends, distributions, funnels, and single metrics. Overlay contextual events on a time-based chart with [`ANNOTATE`](https://shopify.dev/docs/api/shopifyql/latest/syntax/visualize#annotate). ![ShopifyQL query editor with a rendered bar chart preview.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql-next/shopifyql-rendered-output-T6a4Jkoz.png) *** ## References and tutorials Deepen your understanding of ShopifyQL with these references and tutorials. ### References [shopifyqlQuery\ \ ](https://shopify.dev/docs/api/admin-graphql/2026-07/queries/shopifyqlQuery) [Run ShopifyQL through the GraphQL Admin API and receive structured table data.](https://shopify.dev/docs/api/admin-graphql/2026-07/queries/shopifyqlQuery) [Segment query language\ \ ](https://shopify.dev/docs/apps/build/shopifyql/segment-query-language-reference) [Filter customers by their attributes to build segments you can query and save.](https://shopify.dev/docs/apps/build/shopifyql/segment-query-language-reference) ### Tutorials [ShopifyQL editor\ \ ](https://shopify.dev/docs/apps/build/shopifyql/shopify-admin) [Explore, visualize, and save reports with the ShopifyQL code editor in the Shopify admin.](https://shopify.dev/docs/apps/build/shopifyql/shopify-admin) [GraphQL Admin API\ \ ](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api) [Query analytics data programmatically and build ShopifyQL reporting into your app.](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api) [Python SDK and CLI\ \ ](https://shopify.dev/docs/apps/build/shopifyql/python-sdk-and-cli) [Automate ShopifyQL analysis from notebooks, scripts, exports, and command-line workflows.](https://shopify.dev/docs/apps/build/shopifyql/python-sdk-and-cli) ***