Migrating ShopifyQL queries to the new Shopify Analytics
The ShopifyQL Notebooks app will be shut down starting on February 24, 2025. You can no longer install the app from the Shopify App Store, and if you uninstall it, then you can't reinstall it later.
To ensure that you don't lose any data, you can export your datasets from the ShopifyQL Notebooks app at any time before the shutdown date.
You can also manually migrate your ShopifyQL queries to the new Shopify Analytics. Be aware that the new Shopify Analytics uses an updated version of ShopifyQL, so some dataset and dimension combinations might need to be modified during the migration process to return the same data in the new Shopify Analytics as in the ShopifyQL Notebooks app.
On this page
Migrate your existing ShopifyQL queries to the new Shopify Analytics
The new Shopify Analytics uses an updated version of ShopifyQL in all of the default and custom reports, which is different from the version used in the ShopifyQL Notebooks app.
You can manually migrate your existing ShopifyQL queries to the updated version of ShopifyQL in the new Shopify Analytics by creating a custom data exploration using your query. You can then save it as a custom report, and add the custom report as a card to your analytics overview dashboard in your Shopify admin.
You can't automatically migrate your existing queries in bulk.
Learn more about creating custom data explorations using the new Shopify Analytics.
Steps:
From your Shopify admin, go to Settings > Apps and sales channels.
Click ShopifyQL Notebooks.
Click Open app.
In the Notebooks section, click the notebook with the dataset that you want to migrate.
Copy the ShopifyQL query that you want to migrate.
From your Shopify admin, go to Analytics > Reports.
Click New exploration.
In the ShopifyQL query editor, paste your existing query.
Optional: Customize your query to ensure that the query is valid and uses the updated values.
Click ▹ Run.
Click Save.
In the Save report dialog, name your custom report, and then click Save.
Differences between ShopifyQL in Notebooks and the new Shopify Analytics
The new Shopify Analytics uses an updated version of ShopifyQL in all of the default and custom reports, which is different from the version used in the ShopifyQL Notebooks app.
Some combinations of table datasets (used as the FROM
value in a query) and dimensions (used as a SHOW
, GROUP BY
, ORDER BY
, or WHERE
value) have been changed in the updated version of ShopifyQL, which affects how you might write your query.
For example, you can write this ShopifyQL query in the Notebooks app to group total shipping prices by billing country and region:
FROM orders
SHOW shipping
GROUP BY billing_country, billing_region
However, the orders
and shipping
dataset and dimension combination has been updated to be sales
and shipping_charges
in the new Shopify Analytics. So, to migrate that query to the updated ShopifyQL using the new Shopify Analytics, you must modify your query as per the following example:
FROM sales
SHOW shipping_charges
GROUP BY billing_country, billing_region
Updating your datasets
If you choose to recreate your datasets manually using the new Shopify Analytics, or if you choose to migrate your existing ShopifyQL queries from the Notebooks app, then review the following table that lists the changes to some of the dataset and dimension combinations from the Notebooks version of ShopifyQL to the updated analytics version.
If a dataset and dimension combination isn't listed below, then the values remain the same across both versions of ShopifyQL and don't need to be modified in your query to return the same data.
ShopifyQL in Notebooks (dataset > dimension) | ShopifyQL in new Shopify Analytics (dataset > dimension) |
---|---|
orders > discounts_adjustments
| No equivalent. Doesn't exist in new Shopify Analytics. |
orders > gross_sales_adjustments
| No equivalent. Doesn't exist in new Shopify Analytics. |
orders > net_product_quantity
|
sales > net_items_sold
|
orders > ordered_product_quantity
|
sales > quantity_ordered
|
orders > returned_product_quantity
|
sales > quantity_returned
|
orders > shipping
|
sales > shipping_charges
|
products > cart_sessions
|
sessions > sessions_with_cart_additions
|
products > checkout_purchase_sessions
|
sales > sessions_that_reached_and_completed_checkout
|
products > checkout_sessions
|
sessions > sessions_that_reached_checkout
|
products > checkout_to_purchase_rate
|
sessions > checkout_conversion_rate
|
products > purchase_sessions
|
sessions > sessions_that_completed_checkout
|
products > quantity_purchased
|
sales > quantity_ordered
|
products > view_cart_checkout_purchase_sessions
|
sessions > sessions_that_completed_checkout_closed_funnel
|
products > view_cart_checkout_sessions
|
sessions > sessions_that_reached_checkout_closed_funnel
|
products > view_cart_checkout_to_purchase_rate
|
sessions > completed_checkout_rate
|
products > view_cart_sessions
|
sessions > sessions_with_cart_additions
|
products > view_purchase_sessions
|
sessions > sessions_that_completed_checkout
|
products > view_sessions
|
sessions > sessions
|
products > view_to_cart_rate
|
sessions > added_to_cart_rate
|
products > view_to_checkout_rate
|
sessions > reached_checkout_rate
|
products > view_to_purchase_rate
|
sessions > conversion_rate
|
Export your ShopifyQL Notebooks datasets
After ShopifyQL Notebooks is shut down, you won't be able to access the app or reference the datasets within it. If you want to save your existing ShopifyQL Notebooks datasets to reference at a later date, then export them as a CSV file.
Steps:
From your Shopify admin, go to Settings > Apps and sales channels.
Click ShopifyQL Notebooks.
Click Open app.
In the Notebooks section, click the notebook with the dataset that you want to export.
In the code block with the dataset that you want to export, click ..., and then click ↥ Export result as CSV file.
Click Export.