[ Web Proxy ]
URL:
Viewing: https://shopify.dev/docs/apps/build/shopifyql [Back]  [Original]
About ShopifyQLSkip to main content
Docs page [Docs page]Docs page [Docs page]
Apps
Collapse sidebar
Full index

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.

Anchor to How it worksHow 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: 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: Your app sends the query through the shopifyqlQuery field, then renders the same columns and rows in its own UI.
  • Python SDK: The client returns the results as a pandas or polars DataFrame, ready to analyze, join, and export.
  • 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. [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.]

Anchor to Prototype your first query with the ShopifyQL editorPrototype your first query with the ShopifyQL 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

Write a query in the ShopifyQL editor, or use the default reports.

The ShopifyQL editor in the Shopify admin, showing a query, a Run button, and a Refine query prompt for Sidekick. [The ShopifyQL editor in the Shopify admin, showing a query, a Run button, and a Refine query prompt for Sidekick.]

Anchor to Build reporting into your app with the GraphQL Admin APIBuild reporting into your app with the GraphQL 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

Query through the shopifyqlQuery field in your app.

GraphQL query

Copy
{
shopifyqlQuery(
query: "FROM sales SHOW total_sales, orders TIMESERIES day SINCE -7d ORDER BY day ASC"
) {
tableData {
columns {
name
dataType
displayName
}
rows
}
parseErrors
}
}

Anchor to Analyze store data with the Python SDKAnalyze 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

Run queries and work with pandas or polars DataFrames.

Request

Copy
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

day total_sales orders
0 2026-06-10 915.50 14
1 2026-06-11 842.00 12

Anchor to Add analytics into your app with web componentsAdd 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

Render a query as a metric card with s-shopifyql-metric-card.

An s-shopifyql-metric-card web component, showing a heading, a total, and a trend chart rendered from a ShopifyQL query. [An s-shopifyql-metric-card web component, showing a heading, a total, and a trend chart rendered from a ShopifyQL query.]
Was this page helpful?
YesNo
Web Proxy Viewer  |  New URL  |  Original Page