Programming Custom Dashboards
You can modify or replace the SQL, or Structured Query Language, queries in the table and chart blocks of your custom dashboards to fully customize their displayed metrics.
Editing your custom dashboard's SQL queries
You can edit a custom dashboard's SQL queries by opening your dashboard in the Visual Editor.
Begin by selecting the Edit button next to your dashboard inside the dashboards list on the Insights tab. If you don't have a custom dashboard yet, you can select New dashboard from the dashboards list to create one.
You can edit the SQL query or create your own inside the SQL editor in the Options tab on the right. As an alternative, Builder also provides a full-screen text editor that you can open by pressing the Edit full screen button above the editor.
Using JS interpolations, context, and inputs
The syntax for custom dashboard SQL statements is based on Google BigQuery.
Interpolated JS statements have access to the browser's JS API as well as the
You can use
context to get additional information, such as the id of the current content, allowing you to make queries that target only that content.
inputs is populated with the names and values of the inputs that you add to your SQL table or chart. You can add inputs by clicking on Show advanced in the options pane.
In the example below, we've added an enum text field input named
userType that's displayed as a drop down options control on our custom dashboard. You can access the value of this control through
inputs.userType in a JS interpolation.
Querying custom properties and events
You can scope your SQL queries to custom events using the
type column and on the
@events table. You can further refine those queries based on metadata associated with your custom events using the
JSON_EXTRACT_SCALAR SQL function.
For example, the following JS code tracks adding an item to a shopping cart with a
abc123 and the property
somethingElse set to
You can use the following SQL to get every
addToCart event that has a
abc123, including the one tracked above:
WHERE clause uses the type and metadata columns with
JSON_EXTRACT_SCALAR to narrow the scope of returned records.
type = "addToCart"scopes the query to only return
JSON_EXTRACT_SCALAR(metadata, "$.productId") = "abc123"first expands the event's value on the
metadatacolumn, which contains all properties tracked using the
metaproperty on the client side as a JSON object. Then it extracts the
productIdproperty from that object and compares it to
abc123. If the event's
abc123, then it's included in the returned record set.
Running ad hoc SQL queries on custom dashboards
In addition to permanently modifying a dashboard's SQL queries, you can run ad hoc queries on any dashboard on the Insights tab.
To start, open a dashboard from the dashboards list on the Insights tab and select the Toggle SQL button in the upper right corner of any table or chart.
You can use the SQL editor to write your own ad hoc query, which will update your table or chart using the query results. To run your query, select Run at the bottom right of the editor.
Your ad hoc query is added into your browser's current URL as a query parameter, which allows you to share your modified table or chart as a link.
However, your ad hoc query doesn't change the permanent SQL query that retrieves data for your table or chart, and only those with your link can see your modifications. Your ad hoc queries are never persisted.
Default event properties
This is the event type:
Optional, will be in
The date of the event.
Optional, will be in impression events on content that has a/b tests on, and it represents the variation that the user have seen.
Optional, will be in
In all events, represents the session where this event happened.
The maximum bytes that can be queried in one call is
Need Expert help?
Reach out to us, and we will match you with a Builder expert.