SQL Snippets

Overview

SQL snippets are reusable SQL fragments that can be referenced in queries across many reports, filters, and SQL alerts, while being maintained in a single central definition. When the snippet text changes, every query that references it automatically uses the new version.

A snippet is defined by a name (e.g. revenue) and a replacement text (the SQL fragment). To use a snippet in a query, enclose the name in square brackets: SELECT [revenue].

There are two categories of SQL snippets:

• Built-in Snippets — provided by Cluvio with pre-defined behavior.
• Custom Snippets — freely defined name and replacement text, with optional parameters.

Built-in Snippets

Built-in snippets let a SQL query access contextual information about the currently logged-in user or the dashboard displaying the report.

Snippet	Value
[CLUVIO_USER_EMAIL]	E-mail address of the logged-in user, or NULL for sharing links and scheduled e-mails.
[CLUVIO_USER_FIRSTNAME]	First name of the logged-in user, or NULL for sharing links and scheduled e-mails.
[CLUVIO_USER_LASTNAME]	Last name of the logged-in user, or NULL for sharing links and scheduled e-mails.
[CLUVIO_USER_ROLE]	'admin', 'analyst' or 'viewer' for logged-in users, or NULL for sharing links and scheduled e-mails.
[CLUVIO_DASHBOARD_NAME]	Name of the dashboard on which the report or dynamic filter is displayed.
[CLUVIO_DASHBOARD_ID]	ID of the dashboard on which the report or dynamic filter is displayed.

Example query using built-in snippets:

SELECT [CLUVIO_USER_EMAIL], [CLUVIO_USER_FIRSTNAME], [CLUVIO_USER_LASTNAME], [CLUVIO_USER_ROLE],
       [CLUVIO_DASHBOARD_NAME], [CLUVIO_DASHBOARD_ID]

Executed in a dashboard context as:

SELECT 'user@example.com', 'John', 'Doe', 'viewer',
       'Sample Dashboard', '69wx-3kz9-3opj'

Custom Snippets

Custom snippets allow you to extract any SQL fragment into a named, reusable unit.

Basic example

Snippet name: with_us_airports

Snippet text:

WITH us_airports AS (
  SELECT * FROM airports WHERE country='United States'
)

Report query:

[with_us_airports]
SELECT * FROM us_airports WHERE elevation > 1000

Executed as:

WITH us_airports AS (
  SELECT * FROM airports WHERE country='United States'
)
SELECT * FROM us_airports WHERE elevation > 1000

This makes the WITH clause reusable across many reports. Changing the snippet text (e.g. to add a country filter) immediately affects every report that uses it, without requiring individual edits.

Snippets inside Snippets

A snippet's replacement text can itself reference other snippets. The only constraints are:

• The maximum chain length is 10 levels deep (A → B → C → … → J).
• Cycles are not allowed (A → B → A would cause an infinite loop and is rejected).

Parameterized Snippets

A snippet can accept parameters, making it behave like a function. Specify parameter names (comma-separated) in the Params field of the snippet dialog, then use them inside the snippet text enclosed in square brackets.

Call a parameterized snippet by passing arguments in brackets:

SELECT [in_eur(100, 'USD')]

Parameters that are declared but not passed when the snippet is called resolve to a SQL NULL value.

Managing Snippets

All custom snippets are managed from the SQL Snippets overview page, which shows the snippet name, description, and how many reports, filters, or alerts use each snippet.

Creating and Editing

Select Add SQL Snippet to create a new snippet. Every snippet requires:

• Name — used to reference the snippet in queries as [name]. Names may only contain letters, digits, and the characters +, *, _, - (spaces and most special characters are not allowed).
• Text — the SQL fragment to substitute when the snippet is referenced.

The optional Params field (comma-separated parameter names) turns the snippet into a parameterized snippet. The optional Description is shown in tooltips in the report editor and in the overview list.

The Datasource selection only affects code completion in the SQL editor — it has no bearing on where the snippet can be used at runtime.

tip

A snippet can also be created directly from within the report editor. Select the SQL you want to extract and choose Create Snippet from the editor's expanded Run menu. See Report Editor → Creating Snippets.

Actions

From the actions menu on any snippet you can:

• Edit — modify the snippet's name, text, params, description, or datasource.
• Duplicate — create a copy with all settings pre-filled. The new name is generated automatically by appending a numeric suffix (e.g. revenue_1).
• Find Usages — search for all reports, filters, and alerts that reference this snippet. Results open in the global search.
• Delete — permanently remove the snippet.

Deleting a Snippet

Deleting a snippet that is still referenced by reports, filters, or alerts will cause those queries to fail at runtime. Use Find Usages first to check whether the snippet is in use.

Report Editor Integration

Auto-Completion

In the report SQL editor, snippet names appear in the auto-complete suggestions. Select a suggestion to insert the snippet reference.

Snippet Tooltip

Hovering over a snippet reference in the SQL editor shows a tooltip containing the snippet text and description, so you can verify what will be substituted without leaving the editor.

Creating Snippets

To extract part of an existing query into a snippet, select the SQL text you want to extract and choose Create Snippet from the editor's expanded Run menu.

Inlining Snippets

To replace a snippet reference with its literal text — for example, as a starting point for customization — select the snippet name (with or without the surrounding brackets) and choose Inline Snippet from the editor's expanded Run menu.