Queries
Write and save reusable SQL queries to extract insights from your analytics data.
What Are Queries?
Queries are saved SQL templates that run against your analytics event data. Instead of writing the same SQL over and over, you create a query once, give it a name and description, and reuse it whenever you need that insight. Queries are the foundation of the analytics system — they power visualizations and dashboards.
Think of queries as saved questions you can ask of your data. "How many page views did we get this week?" "Which pages have the highest error rate?" "What's the geographic breakdown of our users?" Each of these becomes a reusable query that anyone on your team can run.
daily-active-users or error-rate-by-page. Keys make it easy to reference queries when building dashboards and are more memorable than numeric IDs. Query Parameters
Parameters make queries flexible and reusable. Instead of hard-coding a specific date range or filter value into a query, you define parameters that are filled in each time the query runs. This means a single "page views by date" query can serve as a daily report, a weekly summary, or a monthly overview — just change the date parameter.
Each parameter has a name, a type, and optional settings:
- Name and description — A human-readable label that appears in the query editor and dashboard filters
- Type — Controls what kind of input the parameter accepts and how it is validated
- Default value — A pre-filled value used when the parameter is not explicitly provided
- Required flag — Whether the query can run without this parameter being set
- Sort order — Controls the display order when multiple parameters appear in a form
Parameter Types
| Type | Description | Example Use |
|---|---|---|
| Text | Free-form text input | App names, status filters, search terms |
| Integer | Whole numbers | Result limits, page numbers, thresholds |
| Decimal | Numbers with decimal places | Percentages, conversion rate thresholds |
| Boolean | True or false toggle | Include/exclude flags, feature toggles |
| Date | Calendar date | Start and end dates for date range filters |
| Time | Time of day | Filtering events by hour of day |
| Date and Time | Full timestamp with date and time | Precise time range queries down to the second |
| Array | A list of values of a specific type | Multiple app IDs, a set of page paths to include |
How to Use Queries
The typical workflow for working with queries follows these steps:
- Create a query. Give it a descriptive name, an optional key for easy reference, and write the SQL that answers your question. Use parameter placeholders wherever you want flexible inputs.
- Define parameters. For each placeholder in your SQL, add a parameter definition with a type, description, and optional default value. This tells the system how to present the parameter in the UI and how to validate user input.
- Test the query. Run the query with sample parameter values to verify it returns the expected results. The results come back as columns and rows that you can inspect.
- Connect to a visualization. Once your query works, create a visualization that renders the results as a chart, table, or KPI card.
- Add to a dashboard. Place the visualization on a dashboard and connect the query's parameters to the dashboard's shared filters so users can interact with the data.
Queries and Visualizations
Queries and visualizations work hand in hand. A visualization defines how to display data — as a bar chart, a line graph, a table, or a number. The query defines what data to display. When a visualization runs, it executes its linked query with the current parameter values, then renders the results.
This separation is powerful: you can change the query to refine what data is shown without touching the visualization, or swap the visualization type (say, from a bar chart to a line chart) without changing the underlying query.
Access Control
Queries are protected by the platform's group-based permission system. Each query has its own permissions that control who can:
- View — See the query definition and run it
- Edit — Modify the query's SQL, parameters, and settings
- Manage — Control who else has access to the query
Permissions are assigned to groups, and users inherit access through their group memberships. This means you can give your entire analytics team view access to a set of queries while restricting editing to a smaller group of query authors.