Queries

A TagoSQL query is a resource on your profile, like a device or an analysis: it has a name, tags, a version history, and its own settings. Store the query once; widgets, analyses, and applications execute it by id.

Creating a query

POST /sql
profile-token: <profile-token>

{
  "name": "hot sensors",
  "description": "temperatures above a threshold",
  "query": "SELECT variable, value, time FROM device('DEVICE_ID') AS d WHERE value > $1 ORDER BY time DESC LIMIT 100",
  "params": [{ "key": "$1", "value": "30" }],
  "cache_enabled": true,
  "cache_ttl_seconds": 60
}

The query is validated when you store it: syntax, allowed SQL, and your plan's caps (including the row cap) are all checked before anything is saved. A query that stores cleanly will not fail structurally when executed later.

What a query holds

Field	Meaning
name	Display name (required).
description	Optional free text.
query	The TagoSQL statement.
params	Default values for the query's placeholders. See Parameters.
cache_enabled	Turns the result cache on (off by default). See Executing Queries.
cache_ttl_seconds	How long a cached result stays fresh (up to 24 hours).
rate_limit_rpm	Optional per-query rate cap, useful when one query is exposed to many consumers.
active	An inactive query cannot be executed.
tags	Your own { key, value } labels, also usable to grant execution through Access Management.

Managing queries

Queries are managed like any other TagoIO resource: list them (with field selection, name and tag filters, ordering, and pagination), fetch one, edit, and delete. Editing re-validates the query and drops its cached results. Field-level details and every list parameter are in the TagoIO API reference under SQL Queries.

Versioning

Every save snapshots the query, so you can always see what it looked like and go back:

• Creating a query stores version 1. Each edit that changes the query or params stores the next version; renames and other metadata edits do not create versions.
• Fetch any past revision with GET /sql/{id}/version/{version}. It returns that snapshot's {query, params}.
• To restore, fetch the snapshot you want and save its content back with a regular edit. The restored content becomes the newest version, so the history never rewrites itself.

How many versions are kept depends on your plan (see Limits); beyond the cap, the oldest snapshots are recycled.