Notebook

A notebook is your workspace for data analysis. You can bring SQL, charts, and text together in a single document, with real-time collaborative editing. Access it from the global nav > Notebooks.

A notebook consists of multiple pages. Use a doc page for analysis work, and a grid page for dashboard layouts. You can also use section dividers in the page list.

See notebook permissions for details on permissions.

With real-time collaborative editing, the content of a notebook (SQL, charts, text, and so on) is synced between users who have the same page open. See Parameter for how parameters and run results are synced. To keep parameter operations independent per user, use Version or Report.

Key features

• Folder / Teamspace: placement, access scope, and sorting and filtering the list
• Doc page: a flow-based block editor (insert with /)
• Grid page: tile layout for charts and more. Cross filter
• SQL block: SQL editing, execution, result display, chart creation, and caching
• Running: running SQL per SQL block, per page, or across multiple pages
• Parameter: embedding in SQL, input forms, and placement on grid pages
• Chart: visualization based on dimensions and metrics
• Explorer: explore data with a GUI and create charts or SQL blocks
• Inline table: small tables you edit in a notebook as a sheet or CSV and reference from SQL, with column formulas and lookups from SQL block results
• Comment: comments and mentions in the notebook body
• Version: save, restore, and compare analysis states
• Lock: prevent accidental edits (Unlocked / Query only / Locked)
• Notebook theme: customize chart colors and fonts
• Export and import
• Sharing: permissions / report / public link / signed embed
• FAQ

Creating and managing notebooks

Creating

You can create a notebook in either of the following ways.

1. Open the global nav > Notebooks, then select Create notebook or Create from template.
2. In the folder tree in the left sidebar, open Add notebook or folder and select New notebook. You can also use a template or import a file from the same menu.

On the top screen, you can find notebooks using the Recently viewed, Created by me, Starred, and Active tabs.

Creating from a template

Create from template lets you create a new notebook from one of the available notebook templates. Templates are listed by category. After reviewing a template, select Create from template / Create to create the notebook.

Adding pages

In the page list at the top of the left sidebar inside a notebook, select Add > Page to add a page.

Type	Description
Doc page	A flow-based document format for placing SQL, charts, text, and more.
Grid page	Arranges charts defined on doc pages as a dashboard.
Section divider	Used to divide the page list. It has no body content.

You can Rename, Duplicate page, or Delete a page from that page's menu.

Notebook operations

From the menu in the header inside a notebook, you can perform the following operations.

• Share: grant permissions, and publish reports, public links, or signed embeds
• Export / Import pages
• Notebook theme
• Version
• Lock notebook
• Show dependencies

About this notebook in the header shows details such as the created time and size.

From the list view, you can move, delete, and star notebooks.

Running

Running a notebook means running the SQL in SQL blocks and the SQL that fetches the data needed to render charts, and then getting the results. You can run each SQL block on its own, or run a whole page or multiple pages at once.

Run results are synced between users who have the same notebook open (see Syncing parameter values). Whether you can run SQL depends on your permissions for the target connection.

Run scope

Scope	Action	SQL that runs
SQL block	The SQL block's Run / Run with fresh data	The SQL block, plus the charts and column stats created from its run result.
Page	Run all / Run all with fresh data in the upper right of the main area	Depends on the page type (see the table below).
Multiple pages	Run multiple pages at once	The same SQL as Run all, on each selected page.

The SQL that Run all runs depends on the page type, as follows.

Page	SQL that runs
Doc page	All SQL blocks on the page, plus the charts and column stats created from their run results.
Grid page	The Chart and Query result components placed on the page. Each runs the SQL of the referenced SQL block, with that component's parameter overrides applied. You can't run a component on its own.

Run with fresh data / Run all with fresh data run without using the cache. For keyboard shortcuts, see Keyboard shortcuts.

Running multiple pages at once

1. From the menu next to Run all, select Run multiple pages at once.
2. Select the pages to run. To run without using the cache, turn on Run with fresh data.
3. Select Run (n) pages.

Codatum opens the selected pages one by one and runs Run all on each. When it finishes, you can see which pages had errors and the error messages, and go to the SQL block or chart that failed.

Checking run status

• When parameter or SQL changes make run results outdated, Run all is highlighted. To apply the changes to the run results, run Run all.
• View run stats shows the query time, bytes processed, and cache usage for each SQL in the last Run all.

Lock

Lock is a feature that prevents accidental edits to a notebook. Switch the state from the ⋯ (horizontal three-dot icon) > Lock notebook menu in the header inside a notebook. Changing this setting requires edit permission on the notebook. You can't change the lock state of a notebook you can only access through sharing.

State	Description
Unlocked	Everything can be edited.
Query only	Only parameter changes and SQL execution are allowed.
Locked	Only comments are allowed.

When the state is Query only or Locked, enabling Temporarily unlock lets you remove the lock for yourself only. The lock is automatically restored when you close or reload the notebook.

Dependencies

Open Show dependencies to see a diagram of the SQL blocks and parameters in the notebook, along with their reference relationships. You can also open the same diagram from the menu of a SQL block, a grid component, or a parameter.

Use this to trace references between SQL blocks (SQL chains) and parameter reference chains. See SQL block for details on references between SQL blocks.

Constraints

• You can't edit a notebook once its size exceeds 10MB (see Limits).
• The maximum number of notebooks depends on your contract (see Limits; you can check this from the global nav > Workspace settings > Usage).

Permissions

See Notebook for the conditions for each operation. Whether SQL can be run is determined by permissions on the target connection, not by notebook permissions.