🎛️ Template Variables and Custom Variables

Let's learn how to use Template Variables and Custom Variables to build flexible, reusable, and dynamic dashboards, making data exploration and analysis simpler than ever.

Where to Find Variables in Sentio

Variables can be found in several places throughout the Sentio platform. You might encounter them when:

Inside a Dashboard Panel's SQL Editor: adding a new panel using the "SQL Chart" option, you will find a Parameters button located directly below the SQL editing area. This allows you to define temporary "Custom Variables" to test and debug your query logic with different parameters before saving the panel.

In the Main Dashboard Settings: Click the settings icon (⚙️) located in the top-left corner. From the menu that appears, select "Edit Template Variables" option. This is where you configure the behavior of your variables, such as adding predefined options, or setting default values.

Inside Data Studio's SQL Editor: The Data Studio provides a sandbox environment for data exploration, and it also supports the use of Custom Variables for dynamic querying. This is ideal for exploratory analysis where you want to quickly run a query with different inputs (like various contract addresses or user IDs) without repeatedly editing the query itself.

In the "My Dashboards" Page: Navigate to the "My Dashboards" page (https://dash.sentio.xyz/). Here, you can find an Edit Template Variables option for each dashboard. Additionally, clicking Add Panel from this page will also take you to the panel editor with its Parameters button.

Step-by-Step Guide: Building a Dynamic Dashboard

We will now walk through the most common workflow: creating a dynamic panel in a dashboard to analyze different trading pair and monitor large transactions.

1.Create a Panel with an Initial "Custom Variable"

First, let's create a new panel with an SQL chart. Inside the SQL editor, you can define a Custom Variable to test your logic. These variables exist only within the panel editor session.

Example : Daily Volume & Swap Count

In your dashboard, click "Add Panel" and choose to create a new chart with an SQL query.
In the SQL editor, click the Parameters button to define a new Custom Variable.
Write your SQL query. Notice the special syntax used to reference this in-editor Custom Variable.
Debug your query. You can change the default value of the Custom Variable in the editor to see the chart update instantly, confirming your logic is correct.

2.Save the Panel and Understand the Transition

This is a critical step. When you save the panel to your dashboard, Sentio automatically performs two actions:

It detects that your query uses a Custom Variable.
It promotes this variable to a permanent, dashboard-level Template Variable.

Importantly, the way you reference the variable in your saved query changes. The in-editor reference is converted to the Template Variable syntax.

Old Reference (Custom Variable): ${pair_name}
New Reference (Template Variable): $pair_name

3.Configure the New Template Variable

Now that the variable exists at the dashboard level, you can further configure it to be more user-friendly.

At the top of the dashboard, or by going to the "Edit Template Variables" in your dashboard's settings, You will see your newly created pair_name variable.
Manually add some common options to make it easy for users to select from. (Options should be separated by semicolons.)
Set the default value.

ℹ️
Important Note on Variable Syntax and Default Values
Please be aware that the transition from a Custom Variable (in the editor) to a Template Variable (on the dashboard) also affects how you should format default values for text or string type variables.

For Custom Variables (in the panel editor): When setting a default value, you must wrap the string in single quotes to ensure it is treated as a literal string in the initial query. Example: 'APT-THL'.

For Template Variables (in dashboard settings): Once the variable is saved to the dashboard, the system handles the quoting automatically within the query. Therefore, when you set the default value in the dashboard's variable settings, you should not include the quotes. Example: APT-THL.

This distinction is crucial for ensuring your variables function correctly both during the debugging phase in the editor and in the final interactive dashboard.

4.See it in Action!

Return to your dashboard. You will now see a dropdown menu at the top labeled "pair_name" (or whatever label you provided).
When you select a different token from the dropdown, the panel's chart will instantly refresh to display data for the newly selected token contract.

Important Considerations

Other Entry Points: While this guide focuses on creating variables from a dashboard panel, the principles of defining and referencing them in Data Studio or My Dashboards areas are very similar.
A Note on dash.sentio.xyz and Data Sources: When adding Template Variables in dash.sentio.xyz, the source project must target a data source from an external (public) project.
Reminder on Quotes: Remember to wrap default text values in single quotes ('...') only when defining a temporary Custom Variable in the panel editor, not when setting the final Template Variable in the dashboard settings.