Skip to main content

Run a query with the Python SDK

Analyze a store's commerce data in Python, without building an app UI. In this tutorial, you'll run a ShopifyQL query with the ShopifyQL Python SDK, the shopifyql package, and then work with the results as a pandas DataFrame. To learn when to reach for the SDK instead of the GraphQL Admin API, refer to About the Python SDK.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following:

  • Set up a Python environment with the shopifyql SDK.
  • Run a ShopifyQL query and read the results.
  • Work with the results as a pandas DataFrame.
  • Chart the results over time.

Anchor to RequirementsRequirements

  • Python 3.11 or later installed.
  • A Shopify app that requests the read_reports access scope and has Level 2 access to protected customer data, which ShopifyQL requires. The SDK authenticates as this app, so queries run against a store where it's installed. If you don't have an app yet, you'll scaffold one with the Shopify CLI in Step 1.

Anchor to Step 1: Set up your environmentStep 1: Set up your environment

The SDK authenticates as a Shopify app, so you run queries against a store where your app is installed. The fastest way to start is the Shopify CLI notebook template, which scaffolds an app wired to a Jupyter notebook with the SDK ready to use. You can also install the SDK into an app you already have.

Anchor to Scaffold a notebook with the Shopify CLIScaffold a notebook with the Shopify CLI

The notebook template sets up a Shopify app with a preconfigured Jupyter environment running Python 3.11 or later and the shopifyql SDK installed. Scaffold it with the Shopify CLI:

Terminal

shopify app init --template=https://github.com/Shopify/shopify-app-notebooks-template

Add the redirect URL http://localhost:4545/callback to your app's settings, and then start the app. The Shopify CLI logs in to your Partner account, connects the app, and writes your app credentials to a local .env file.

Terminal

shopify app dev

These credentials are what the SDK uses to complete the OAuth flow in Step 2, so you authenticate from the notebook itself and never paste a token by hand.

Anchor to Install the SDK in an existing appInstall the SDK in an existing app

To add the SDK to an app you already have, install the package with pandas and polars support:

Terminal

pip install "shopifyql[all]"

On this path, you construct the client yourself in Step 2, using your store's subdomain and the offline access token your app already holds. For how apps obtain and store that token, refer to Offline access tokens.

Anchor to Step 2: Run a queryStep 2: Run a query

How you create the client depends on the path you chose in Step 1. Either way, pass the store's subdomain as shop, without the .myshopify.com suffix.

On the notebook template path, authenticate with from_oauth. The first time you run this, the SDK opens your browser to finish the OAuth flow on http://localhost:4545/callback, and then returns an authenticated client.

Python

from shopifyql import ShopifyQLClient

client = ShopifyQLClient.from_oauth(shop="your-store")

records = client.query(
"FROM sales SHOW total_sales, orders TIMESERIES day SINCE -7d ORDER BY day ASC"
)

from_oauth reads the app's API key and secret from the SHOPIFY_API_KEY and SHOPIFY_API_SECRET environment variables, which the notebook template sets from .env. To call from_oauth outside the template, set both variables first, or pass key and secret to the call.

On the existing-app path, construct the client directly with the offline access token your app holds. Read the token from your app's session layer rather than hard-coding it, and then call the same query methods.

Python

from shopifyql import ShopifyQLClient

client = ShopifyQLClient(shop="your-store", access_token=access_token)

The query uses FROM and SHOW to read the sales dataset, returning total sales and orders, one row per day for the last 7 days. client.query() returns those rows as records. If the query is invalid or the response comes back without valid table data, then it raises a ValueError instead.

Anchor to Step 3: Work with the results as a DataFrameStep 3: Work with the results as a DataFrame

For analysis workflows, get the results directly as a pandas DataFrame:

Python

df = client.query_pandas(
"FROM sales SHOW total_sales, orders TIMESERIES day SINCE -7d ORDER BY day ASC"
)
print(df.head())

Anchor to Step 4: Chart the resultsStep 4: Chart the results

The DataFrame is typed. DAY_TIMESTAMP columns come back as datetimes and MONEY columns as floats, so it plots without further conversion. Use the built-in pandas plot() method, which renders with matplotlib. Install matplotlib if it isn't already available:

Terminal

pip install matplotlib

Query the data sorted from oldest to newest, and then plot the metric against the day:

Python

import matplotlib.pyplot as plt

df = client.query_pandas(
"FROM sales SHOW total_sales TIMESERIES day SINCE -7d ORDER BY day ASC"
)

df.plot(x="day", y="total_sales", title="Total sales, last 7 days")
plt.show()

From here, you can join the DataFrame with other data or export it to a data warehouse.

Anchor to Next stepsNext steps

In the SDK, results and errors are ordinary Python. A successful query returns records or a DataFrame, and a failed one raises an exception. The SDK doesn't surface the parseErrors list or the shopifyqlCost budget directly, so the next page covers the GraphQL Admin API model they map onto.

Handle errors and budgets

The GraphQL Admin API model for parse errors, rate limits, and query cost.

ShopifyQL reference

Browse every dataset, metric, and dimension.

Build a sales dashboard with the GraphQL Admin API

Build reporting into an app instead of a notebook.

Was this page helpful?