Authoring and running notebooks - Amazon Redshift
Importing into notebooks
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Authoring and running notebooks

You can use notebooks to organize, annotate, and share multiple SQL queries in a single document. You can add multiple SQL query and Markdown cells to a notebook. Notebooks provide a way to group queries and explanations associated with a data analysis in a single document by using multiple query and Markdown cells. You can add text and format the appearance using Markdown syntax to provide context and additional information for your data analysis tasks. You can share your notebooks with team members.

If you have lots of existing queries that you want to put into notebooks, consider using the Import, Import query feature of the query editor v2 notebooks page to add queries to a new or existing notebook.

To use notebooks, you must add permission for notebooks to your IAM principal (an IAM user or IAM role). As a best practice, we recommend attaching permissions policies to an IAM role and then assigning it to users and groups as needed. For more information, see Identity and access management in Amazon Redshift. You can add the permission to one of the query editor v2 managed policies. For more information, see Accessing the query editor v2.

You can Run all the cells of a notebook sequentially. The SQL query cell of a notebook has most of the same capabilities as a query editor tab. For more information, see Authoring and running queries. The following are differences between a query editor tab and a SQL cell in a notebook.

  • There isn't a control to run Explain on a SQL statement in a notebook.

  • You can create only one chart per SQL cell in a notebook.

You can export and import notebooks to files created with query editor v2. The file extension is .ipynb and the file size can be a maximum of 5 MB. The SQL and Markdown cells are stored in the file. A cluster or workgroup and database is not stored in the exported notebook. When you open an imported notebook you choose the cluster or workgroup and the database where to run it. After running SQL cells, you can then choose in the results tab whether to display the current page of results as a chart. The result set of a query is not stored in the notebook.

When you run a notebook, either with Run all or Run, then a Run status panel becomes available. Choose the Run status icon to open the panel. This panel contains a summary of the status of the most recent Run all or Run of the SQL cells in your notebook. If you run multiple SQL cells you can view at a glance the status, elapsed time, and some details about the run. You can filter the cells displayed based on status: All, Succeeded, Error, In progress, or Canceled. You can also use this panel to navigate to a SQL cell in the editor.

To create a notebook

  1. From the navigator menu, choose Editor Editor.

  2. Choose , and then choose Notebook.

    By default, a SQL query cell appears in the notebook.

  3. In the SQL query cell, do one of the following:

    • Enter a query.

    • Paste a query that you copied.

  4. (Optionally) Choose the New Markdown cell icon, then choose Markdown to add a Markdown cell where you can provide descriptive or explanatory text using standard Markdown syntax.

  5. (Optionally) Choose the New SQL cell icon, then choose SQL to insert a SQL cell.

You can rename notebooks using the Rename (pencil) icon.

From the More (more) menu, you can also perform the following operations on a notebook:

  • Share Share with my team – To share the notebook with your team as defined by tags. For more information, see Sharing a query

  • Export Export – To export the notebook to a local file with the .ipynb extension.

  • Import query Import query – To import a query from a local file into a cell in the notebook. You can import files with .sql and .txt extensions.

  • Save Save version – To create a version of the notebook. To see versions of a notebook, navigate to your saved notebooks and open Version history.

  • Duplicate Duplicate – To create a copy of the notebook and open it in a new notebook tab.

  • Shortcuts Shortcuts – To display the shortcuts available when authoring a notebook.

To open a saved notebook

  1. From the navigator menu, choose Notebooks Notebooks. Your saved notebooks and notebook folders are displayed.

  2. Choose the notebook that you want to open and double-click it.

You can show My notebooks, notebooks that are Shared by me, and notebooks that are Shared to my team within the notebooks tab.

From the context menu (right-click) of a notebook you can perform the following operations:

  • Open notebook – To open the notebook in the editor.

  • Save version – To save a version of the notebook.

  • Version history – To display the versions of a notebook. From the Version history window you can delete and revert versions. You can also create a notebook from the currently selected version.

  • Edit tags – To create and edit tags on a notebook.

  • Share with my team – To share a notebook with your team.

    To share a notebook with your team, make sure that you have the principal tag sqlworkbench-team set to the same value as the rest of your team members in your account. For example, an administrator might set the value to accounting-team for everyone in the accounting department. For an example, see Permissions required to use the query editor v2 .

  • Export – To export a notebook to a local file.

  • Rename – To rename a notebook.

  • Duplicate – To make a copy of a notebook.

  • Delete – To delete a notebook.

Importing into notebooks

You can import an entire notebook or individual SQL cells into a query editor v2 notebook.

To import an entire notebook from a local file to My notebooks, choose Import Import, then choose Import notebook. Navigate to the .ipynb file that contains your notebook. The notebook is imported into the currently open notebook folder. You can then open the notebook in the notebook editor.

To import a query from a local file into a SQL cell in a notebook, choose Import Import, then choose Import query. On the Import query window, follow the directions on the screen to choose file and folders that can be imported as a query into a new notebook or an existing notebook. The files must have an extension of .sql or .txt. Each query can be up to 10,000 characters. When you add to an existing notebook, you choose which notebook from all notebooks in your Saved notebooks list. The imported queries are added as SQL cells at the end of the notebook. When you choose a new notebook, you choose the name of the notebook and it is created in the currently open saved notebooks folder.

Note

When creating .sql files on macOS using the TextEdit application, you might encounter an issue where an additional hidden extension is added to the file. For instance, a file named Test.sql created in TextEdit might end up being saved as Test.sql.rtf. The query editor v2 does not support files with the .rtf extension. However, if you create a .sql file using TextEdit, and save it as a plain text file, the file has an additional hidden .txt extension. For example, a file named Text.sql might be saved as Text.sql.txt. Unlike the .rtf extension, query editor v2 does support files with the .txt extension, so Text.sql.txt is supported when importing queries to notebooks.

For a demo of notebooks, watch the following video.