Query Beta

Query (sometimes called a saved query) lets you save SQL to reuse per connection. You can reference the same SQL from multiple notebooks, or run it directly from the query screen. Open it from global nav > Queries.

There's no dedicated resource role. What you can do depends on the permissions of the connection it belongs to. See Query permissions for details.

INFO

This feature is in beta. The specification might change without notice.

Key features

• Saving and running SQL: Edit and save SQL on the query screen, then run it with Run.
• Organizing with folders: Organize queries under each connection.
• Notebook integration: Save SQL from a SQL block, and reference a saved query with / (see SQL block).
• Queries tab in the catalog: View and edit metadata (description, tags, columns, references, popularity, and so on).
• Workflow: Run a saved query on a schedule.
• Tags: Add query tags. Definitions are managed in workspace settings.

Creating a query

From the query screen

1. Open global nav > Queries.
2. Select New query (opens a draft where you can choose a connection).
3. Edit the SQL, then select Save and specify a name, connection, and folder to save it for real.

Selecting New query from a connection or folder in the left sidebar creates an empty query directly at that location. You can also create and move folders from the left sidebar.

From a notebook

1. Select Save SQL from the menu at the top right of a SQL block.
2. Specify a name, connection, and folder, then save.

Saving behaves as follows.

• References to other SQL blocks or saved queries are saved as expanded SQL strings.
• Parameters are saved with their current values substituted in.
• The description automatically includes a link back to the source notebook (Source notebook: ...).
• If a recent execution result exists, column information can also be saved.

Editing, running, and managing

Action	Description
Save / Save as...	Updates the SQL, name, and so on. You can also save as a copy
Run	Runs the SQL using the credentials of the connection it belongs to
Star	Add or remove from the Starred tab in the list, and from quick search
Description/tags	Edit from the query detail, or from the catalog
Columns	You can add descriptions and tags (managed based on the columns from execution results)
Create notebook	Creates a new notebook that includes this query
Move/delete	Available from the left sidebar or the detail menu. You can only move within the same connection
History	View past versions

Once saved, you can't change the connection a query belongs to. To use a different connection, recreate it as a new query with Save as... or similar.

Integration with notebooks

• Referencing: In a SQL block, type / and insert from Saved query. This embeds the SQL as of the time you inserted it, and that embedded SQL is what runs. If the source query changes, the reference chip shows Diff found, and you can apply it with Update embedded query.
• Saving: Save SQL turns references and parameters into fixed, expanded SQL.

See SQL block for the notebook side of this.

Constraints

• You can't change which connection a query belongs to (after saving).
• You can only move a query or folder within the same connection.
• Folders can be nested up to 5 levels deep (Limits).
• Deleting a folder also deletes the queries in it.
• The maximum number of queries depends on your contract (Limits; check under global nav > Workspace settings > Usage).
• Deleting a connection also deletes its related saved queries.

Permissions

See Query permissions for the conditions for each action. Viewing requires a connection's read-level permission; editing, running, and folder operations require its run permission.