Add saved queries
A saved query gives widgets data. It names a connection and an operation that an administrator approved, and says which value each operation parameter gets. Widgets read the result by its result name (variableName).
You need edit rights on the dashboard (Contributor on your own dashboards, Editor or Coordinator on any).
In the web app
- Open the dashboard and turn on Edit Mode.
- Open the settings menu (the gear in the dashboard header) and choose Saved queries.
- Select Add query.
- Type a Result name, such as
trips. It must be unique in the dashboard. A short name without spaces is easiest to use later. - Choose the Connection and the Operation. The lists show only active, read-only operations you are allowed to use.
- Fill Parameters (JSON). See Parameter values below.
- Select Apply to draft. The dashboard saves on its own.
If the lists show The approved query catalog is unavailable or access was denied, the server has no query catalog configured, or you lack edit rights. Saved queries that already exist keep running.
Parameter values
Each parameter is either a fixed value or a value from a dashboard filter.
| Kind | Shape | Use it for |
|---|---|---|
| Literal | { "kind": "literal", "value": 30 } | A value that never changes |
| Filter | { "kind": "filter", "key": "vehicle" } | The current value of filter vehicle |
A filter binding takes two optional fields:
| Field | Effect |
|---|---|
defaultValue | Used when the filter has no value. An explicit empty string does not use it. |
omitWhenEmpty | Leaves the parameter out when the value is missing or an empty string, after the default is applied. Use it for optional operation parameters. |
Values are JSON scalars (text, number, true, false, null) or flat lists of scalars. They are never expressions, objects or SQL.
A literal is not a security control. An editor can change it. Anything that must hold for every viewer, such as the organization’s ID, belongs in the operation itself, which only an administrator can change. See Queries and connections.
Use the result in a widget
In the widget’s Settings, set Data Source to Planner and choose the result name as the Variable. In text fields, write the column in double braces: {{completed}}. Widgets that show one value read the first row; tables and lists read every row.
In the document, the same binding is two fields in the widget’s config:
{ "dataMode": "planner", "plannerVariableName": "trips" }Limits
| Limit | Value |
|---|---|
| Saved queries per dashboard | 50 |
| Identifier length | 128 characters |
| Text value length | 2,048 characters |
| Values in one list | 100 |
| Rows per result | 5,000 |
| Result size | 2 MiB |
| Time per query | 20 seconds |
All limits are in Limits.
Related
- Add filters
- Connect PostgREST and Connect BigQuery, for administrators