# Queries

> Save SQL as a query, add parameters with {{ name }}, and give it a chart. How results are kept, and how metric queries differ from SQL.

Source: https://tini.so/docs/queries

A **query** is a saved question for one data source. It holds the SQL, an optional description, and at most one chart. Saved queries are what dashboards and notebooks are made of.

## Create a query

There are a few ways to start one:

- **Queries → New query** opens an empty query on your organization’s first data source. Change the data source from the picker next to the editor.
- **Save as query** in the [SQL Editor](https://tini.so/docs/sql-editor).
- **Query this table** in [Explore](https://tini.so/docs/explore).
- Ask the [agent](https://tini.so/docs/agent) to save a chart: it saves the query behind it.

The **Queries** page lists every saved query with its data source, who created it and when it last ran.

## The query page

- **Name and description.** Click the title to rename it. The description is optional: on dashboards, a chart shows an info icon that reveals it, so use it to say what the number means.
- **Run** (⌘ ↵) runs the query. **Save** (⌘ S) saves your changes. Changing the data source saves right away.
- **Data Preview** shows the result as a table; **Chart** turns it into a chart. See [Charts](https://tini.so/docs/charts).
- **Delete query** is in the **⋯** menu. Dashboards that show its chart lose that widget.

## Results

A query returns at most 5,000 rows and stops after 30 seconds. Orcabase keeps the latest result of every saved query, and dashboards show that saved result, so they open instantly without running anything. A result is replaced each time the query runs; older results aren’t kept.

## Parameters

A parameter is a blank in your SQL that you fill in before running it. Write it as `{{ name }}`:

```sql
SELECT date_trunc('week', created_at) AS week, SUM(amount) AS revenue
FROM orders
WHERE country = {{ country }}
  AND created_at >= {{ since }}
GROUP BY week
ORDER BY week
```

A box for each parameter appears above the editor. Type the values (`VN`, `2025-01-01`) and run. Values are text: the database converts them where the SQL expects a number or a date.

### How values are sent

| Data source | How a value reaches the database |
| --- | --- |
| PostgreSQL | As a real query parameter, separate from the SQL |
| BigQuery | As a named query parameter, separate from the SQL |
| DuckDB | Inserted into the SQL as quoted text. It’s escaped, so it can’t break out of the quotes, but it always arrives as text: use `CAST({{ n }} AS INTEGER)` where you need a number. |

> **Note**
>
> Parameter values aren’t saved with the query. A dashboard shows the chart from the query’s last run, and **Run all queries** on a dashboard runs each query with its parameters empty. For dashboard charts, queries without parameters work best.

## Metric queries

A query can also ask for [metrics](https://tini.so/docs/metrics) by name instead of holding SQL: revenue and orders, by month, last 90 days. Orcabase writes the SQL each time it runs, from the current metric definitions, so the chart stays right when a definition changes. See [Explore and query metrics](https://tini.so/docs/metric-queries).

---

Previous: [SQL Editor](https://tini.so/docs/sql-editor.md) · Next: [Charts](https://tini.so/docs/charts.md)

All docs: https://tini.so/llms.txt