Creating Notebooks

The ShopifyQL Notebooks app enables you to query your store data and create visualizations. By combining different data visualization with text blocks, you can create reports on your store called notebooks. For example you can create a notebook to explore your total product sales, and a notebook to help you understand which products are making the biggest contribution to your profit margins. You can create as many notebooks as you want.

Install the ShopifyQL notebooks app

Go to the ShopifyQL Notebooks page on the Shopify app store.
Click Add app.
Log in to the Shopify store that you want to install the ShopifyQL Notebooks app on.
To agree to share the required data with the ShopifyQL Notebooks app, click Install app.

After the app is installed on your store, you can create a new notebook.

Creating a new notebook

A notebook is a set of content blocks that you create and put in the order that you want. There are different types of blocks that you can use to create your notebook:

You can use a combination of data visualizations such as graphs and charts, as well as text to best tell the data story.

Create a new notebook

From your Shopify admin, click Settings > Apps and sales channels.
From the Apps and sales channels page, click ShopifyQL Notebooks.
Click Open app.
Click Create notebook.
By default, the new notebook has a single codeblock. Do either of the following:
- Choose a template for your code block
- Write your own code block
Optional: Add additional code blocks or text blocks to your notebook by hovering your mouse where you want to add the block, and selecting either Text block or Code block.
To save your notebook, click the ... button, and then click Name.
Enter a name for your notebook, and then click Save.

After you save your notebook, you can export the notebook, or edit the notebook.

Text blocks

A text block lets you add styled text or a static image to your notebook. Text blocks can be used for headings in your notebooks, introductions, or descriptions of data visualizations.

Code blocks

Code blocks let you add a a query to your notebook that uses the ShopifyQL query language to return data about your store. In your code block you can choose how the data displayed in your notebook. Learn more about using ShopifyQL for Notebooks.

Templates

Templates are pre-written ShopifyQL queries that you can use as-is, or as a starting place to create your own query. When you create a code block, you can select a template by clicking Templates and selecting a template from the list. Templates are available for a number of data visualizations, for example:

Sales over time
Top converting products
Top selling products

Autocompletion

ShopifyQL Notebooks automatically provide suggestions for your query as you write your code block. Click the suggestion to add it to your query, or continue typing to add your own code.

Export a notebook

From your Shopify admin, click Settings > Apps and sales channels.
From the Apps and sales channels page, click ShopifyQL Notebooks.
Click Open app.
In the Notebooks section, click the notebook that you want to export.
Click the ... button, and then click Presentation mode.
Click Export.

Your notebook is downloaded as a PNG file.

Edit a notebook

From your Shopify admin, click Settings > Apps and sales channels.
From the Apps and sales channels page, click ShopifyQL Notebooks.
Click Open app.
In the Notebooks section, click the notebook that you want to edit.
Make changes to the notebook by editing blocks, adding new blocks, or deleting blocks.
Click Save to save your changes.

Using Liquid to reference data

You can create dynamic data stories using Liquid, Shopify's templating language, to reference data in your ShopfyQL Notebooks. A reference is a data element from a ShopifyQL code block, and it can be edited using Liquid within a text block.

Steps:

From your Shopify admin, click Settings > Apps and sales channels.
From the Apps and sales channels page, click ShopifyQL Notebooks.
Click Open app.
In the Notebooks section, click the notebook that you want to edit.
Find the text where you want to create a reference.
Click Add reference to open the Liquid editor.
Enter the Liquid code for the data element that you want to reference.
Use the autocomplete suggestions for available references, rows, and columns to ensure accuracy.
Click Apply to save your reference.

Running a Notebook

When you load a ShopifyQL Notebook, you are presented with code and text blocks in their previously-run state. You can use this view to understand prior work, but it might not show the latest data. To view current data, use one of the following options:

Re-run individual code blocks: To get the latest data, re-run the relevant code blocks by clicking Run for each code block.
Run all the code blocks: Update all of the data in your notebook and run all of the code blocks by clicking Run all.

When re-running a code block, any references linked to it are updated automatically, so your data stories show the latest information.