--- title: About ShopifyQL description: >- ShopifyQL is Shopify's commerce analytics query language. Write a query once and run it in the Shopify admin, the GraphQL Admin API, or the Python SDK. source_url: html: 'https://shopify.dev/docs/apps/build/shopifyql' md: 'https://shopify.dev/docs/apps/build/shopifyql.md' api_name: shopifyql --- # ShopifyQL ShopifyQL turns a store's commerce data into structured results your app and its users can chart, embed, and act on. It's Shopify's commerce analytics query language, and the same query runs in the Shopify admin, your app, or a notebook. ## How it works Every query has the same shape. `FROM` picks a dataset, `SHOW` lists the metrics and dimensions to return, and clauses such as `WHERE`, `TIMESERIES`, and `ORDER BY` shape the rest. It returns `tableData`, a rendering-agnostic set of typed `columns` and `rows`, so the same result takes a different form on each surface: * **[Shopify admin](https://shopify.dev/docs/apps/build/shopifyql/build-your-first-query)**: The ShopifyQL editor in the Shopify admin runs your query and draws the `columns` and `rows` as a chart or table, so you can learn the language before you write any code. * **[GraphQL Admin API](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api)**: Your app sends the query through the `shopifyqlQuery` field, then renders the same `columns` and `rows` in its own UI. * **[Python SDK](https://shopify.dev/docs/apps/build/shopifyql/python-sdk)**: The client returns the results as a pandas or polars DataFrame, ready to analyze, join, and export. * **[Web components](https://shopify.dev/docs/api/shopifyql/latest/web-components)**: A prebuilt `s-shopifyql-metric-card` runs the query and renders the same `columns` and `rows` as a chart, table, or list in an embedded app. ![A flow diagram showing a ShopifyQL query returning tableData, a set of typed columns and rows. The result is rendering-agnostic, so each surface renders it differently, such as a chart in the Shopify admin, custom UI in an app, or a DataFrame in the Python SDK.](https://shopify.dev/assets/assets/images/shopifyql/how-it-works-light-D3JJfttV.svg) *** ## Prototype your first query with the Shopify​QL editor Start in the Shopify admin. You write a query against a real store and see the results render as you type, with no app to build, no access token to manage, and no GraphQL to wire up. Learn the shape of the language, refine a query until it returns what you want, then take the exact query to code. [Build your first query\ \ ](https://shopify.dev/docs/apps/build/shopifyql/build-your-first-query) [Write a query in the ShopifyQL editor, or use the default reports.](https://shopify.dev/docs/apps/build/shopifyql/build-your-first-query) ![The ShopifyQL editor in the Shopify admin, showing a query, a Run button, and a Refine query prompt for Sidekick.](https://shopify.dev/assets/assets/images/apps/shopifyql/shopifyql-admin-editor-C2GgfS_U.png) *** ## Build reporting into your app with the Graph​QL Admin API Bring store analytics into the apps you build. Send a query through the `shopifyqlQuery` field, get back structured `tableData`, and render it in your own UI as the dashboards, reports, and insights your users act on. The query you prototyped in the Shopify admin runs unchanged from code. [GraphQL Admin API\ \ ](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api) [Query through the `shopifyqlQuery` field in your app.](https://shopify.dev/docs/apps/build/shopifyql/graphql-admin-api) ## GraphQL query ```graphql { shopifyqlQuery( query: "FROM sales SHOW total_sales, orders TIMESERIES day SINCE -7d ORDER BY day ASC" ) { tableData { columns { name dataType displayName } rows } parseErrors } } ``` *** ## Analyze store data with the Python SDK Get store data into a DataFrame you can analyze, join, and export. The Python SDK runs ShopifyQL from a notebook or a script and returns results as pandas or polars DataFrames, so data analysts and scientists work in the tools they already use. It's the same query language as the Shopify admin and the GraphQL Admin API, so a query you refined in the admin runs unchanged in your notebook. [Python SDK\ \ ](https://shopify.dev/docs/apps/build/shopifyql/python-sdk) [Run queries and work with pandas or polars DataFrames.](https://shopify.dev/docs/apps/build/shopifyql/python-sdk) ## Request ```python from shopifyql import ShopifyQLClient client = ShopifyQLClient.from_oauth(shop="your-store") df = client.query_pandas( "FROM sales SHOW total_sales, orders TIMESERIES day SINCE -7d ORDER BY day ASC" ) print(df) ``` ## Response ```text day total_sales orders 0 2026-06-10 915.50 14 1 2026-06-11 842.00 12 ``` *** ## Add analytics into your app with web components Add live analytics to an embedded app without building your own charts. A prebuilt `s-shopifyql-metric-card` runs a ShopifyQL query and renders the result as a chart, table, or list, so your app shows a store's metrics with no charting code of your own. It's the same query you prototyped in the Shopify admin, wrapped in a component you drop into your app's UI. [Analytics web components\ \ ](https://shopify.dev/docs/api/shopifyql/latest/web-components) [Render a query as a metric card with `s-shopifyql-metric-card`.](https://shopify.dev/docs/api/shopifyql/latest/web-components) ![An s-shopifyql-metric-card web component, showing a heading, a total, and a trend chart rendered from a ShopifyQL query.](https://shopify.dev/assets/assets/images/landing-pages/templated-apis/shopifyql/shopifyql-metric-card-anatomy-light-Cnn6DjgS.svg) ***