TAtago
SQL Queries

Create SQL Query

Changed on

Create a saved TagoSQL query on your profile. The query is parsed and validated against your plan at save time and snapshotted as version 1. Enforces the saved-query count (sql_query) and parameter count (sql_query_params) plan caps. Server-owned fields (id, profile, cache_version, version, versions, created_at, updated_at) are never accepted from the request body. The request body cap is 64 KiB.

post/sql

Request

Request body

namestring required

Required, 1..=64 chars.

descriptionstring

Optional, <=1024 chars.

querystring required

Required. Read-only TagoSQL, validated against your plan at save time.

cache_enabledboolean

Enables the result cache on execute. Default false.

cache_ttl_secondsinteger

Clamped to 0..=86400 (24h). A TTL of 0 disables caching regardless of cache_enabled.

rate_limit_rpminteger

Optional, >=1. Per-query soft rate cap, clamped down to the plan's rpm_sql_execute hard cap. Rejected at save time if it exceeds the hard cap.

activeboolean

Default true. An inactive query cannot be executed.

Example request

{
  "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,
  "rate_limit_rpm": 30,
  "active": true,
  "tags": [
    {
      "key": "kind",
      "value": "report"
    }
  ]
}

Response

Saved query created (snapshotted as version 1).

statusboolean

Example response

{
  "status": true,
  "result": {
    "id": "6a1b2c3d4e5f6a1b2c3d4e5f",
    "name": "hot sensors",
    "version": 1,
    "cache_version": 1
  }
}

Changes