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.

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:

  1. From your Shopify admin, go to Settings > Apps and sales channels.

  2. Click ShopifyQL Notebooks.

  3. Click Open app.

  4. In the Notebooks section, click the notebook with the dataset that you want to migrate.

  5. Copy the ShopifyQL query that you want to migrate.

  6. From your Shopify admin, go to Analytics > Reports.

  7. Click New exploration.

  8. In the ShopifyQL query editor, paste your existing query.

  9. Optional: Customize your query to ensure that the query is valid and uses the updated values.

  10. Click ▹ Run.

  11. Click Save.

  12. 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.

Table listing the dataset and dimension combinations from ShopifyQL Notebooks that have been updated in the new Shopify Analytics.
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:

  1. From your Shopify admin, go to Settings > Apps and sales channels.

  2. Click ShopifyQL Notebooks.

  3. Click Open app.

  4. In the Notebooks section, click the notebook with the dataset that you want to export.

  5. In the code block with the dataset that you want to export, click ..., and then click ↥ Export result as CSV file.

  6. Click Export.

Can’t find the answers you’re looking for? We’re here to help.