About the Python SDK
The ShopifyQL Python SDK runs a query from a notebook or a script. It returns the results as a pandas or polars DataFrame, ready for analysis, joins, and export. Use it when you want to analyze or export a store's commerce data instead of building an app UI. To build reporting into an app, use the GraphQL Admin API instead, which returns structured tableData for you to render in your app's UI.
Anchor to How it worksHow it works
The shopifyql package wraps the GraphQL Admin API so you work in Python instead of raw GraphQL. It authenticates as a Shopify app, so it needs your store's subdomain and an access token for an app installed on that store. How you get that token depends on where you run the SDK:
- In a Shopify CLI notebook, the
from_oauthhelper completes the OAuth flow and gets the token for you. - In your own app, you pass the offline access token the app already holds. For how apps obtain and store it, refer to Offline access tokens.
You create a client, then call a query method with a ShopifyQL string, where FROM and SHOW name the dataset and the metrics to return. Each method returns the same data in a different shape:
client.query()returns records.client.query_pandas()returns a pandas DataFrame.client.query_polars()returns a polars DataFrame.
Python
Running a query needs the read_reports access scope and Level 2 access to protected customer data.
Running a query needs the read_reports access scope and Level 2 access to protected customer data.
