SQL

Manage and run TagoSQL queries on your profile.

list

Retrieves a list with all TagoSQL queries from the profile.

See: TagoSQL Queries

Parameters:

Optional queryObj: SQLQuery(Query)
Query parameters to filter the results.
Default queryObj:
queryObj = {
    "page": 1,
    "fields": ["id", "name", "tags"],
    "filter": {},
    "amount": 20
}

Returns:

list[SQLInfo]
# If receive an error "Authorization Denied", check policy "SQL Query" / "Access" in Access Management.
from tagoio_sdk import Resources

resources = Resources()
result = resources.sql.list({
    "page": 1,
    "fields": ["id", "name", "tags"],
    "amount": 20
})
print(result)  # [ { 'id': 'query-id-123', 'name': 'My query', ... } ]

create

Creates a new TagoSQL query on the profile.

See: TagoSQL Queries

Parameters:

sqlObj: SQLCreateInfo
Query definition.

Returns:

from tagoio_sdk import Resources

resources = Resources()
result = resources.sql.create({
    "name": "Latest temperature",
    "query": "SELECT variable, value, time FROM device($1) AS d WHERE variable = 'temperature' ORDER BY time DESC LIMIT 10",
    "params": [{"key": "$1", "value": "my-device-id"}]
})
print(result)  # { 'id': 'query-id-123', 'name': 'Latest temperature', ... }

info

Retrieves detailed information about a specific TagoSQL query.

See: TagoSQL Queries

Parameters:

sqlID: str
Query ID.

Returns:

# If receive an error "Authorization Denied", check policy "SQL Query" / "Access" in Access Management.
from tagoio_sdk import Resources

resources = Resources()
result = resources.sql.info("query-id-123")
print(result)  # { 'id': 'query-id-123', 'name': 'My query', 'query': 'SELECT ...', ... }

edit

Replaces a TagoSQL query. The query is re-validated and its cached results are dropped; a new version is stored when the query or the params change.

See: TagoSQL Queries

Parameters:

sqlID: str
Query ID.
sqlObj: SQLCreateInfo
New query definition.

Returns:

from tagoio_sdk import Resources

resources = Resources()
result = resources.sql.edit("query-id-123", {
    "name": "Latest temperature",
    "query": "SELECT variable, value, time FROM device($1) AS d ORDER BY time DESC LIMIT 20",
    "params": [{"key": "$1", "value": "my-device-id"}]
})
print(result)  # { 'id': 'query-id-123', 'version': 2, ... }

delete

Deletes a TagoSQL query from the profile.

See: TagoSQL Queries

Parameters:

sqlID: str
Query ID.

Returns:

dict[str, str]
from tagoio_sdk import Resources

resources = Resources()
result = resources.sql.delete("query-id-123")
print(result)  # { 'id': 'query-id-123' }

getVersion

Retrieves a historical snapshot (query and params) of a TagoSQL query. To restore it, send the snapshot’s query and params back with edit.

See: TagoSQL Queries

Parameters:

sqlID: str
Query ID.
version: int
Version number to retrieve.

Returns:

from tagoio_sdk import Resources

resources = Resources()
result = resources.sql.getVersion("query-id-123", 1)
print(result)  # { 'query': 'SELECT ...', 'params': [], 'created_at': ... }

execute

Executes a TagoSQL query. Params sent here override the saved defaults per key; test: True skips the result cache entirely.

See: Executing Queries

Parameters:

sqlID: str
Query ID.
Optional executeObj: SQLExecuteObj
Execution options.

Returns:

# If receive an error "Authorization Denied", check policy "SQL Query" / "Execute" in Access Management.
from tagoio_sdk import Resources

resources = Resources()
result = resources.sql.execute("query-id-123", {
    "params": [{"key": "$1", "value": "my-device-id"}]
})
print(result)  # { 'columns': [...], 'rows': [...], 'row_count': 1, ... }

tables

Retrieves the TagoSQL schema discovery catalog: the virtual table families with their typed columns, plus the profile’s devices and entities. Pass entity_id to resolve one entity’s columns.

See: Available Tables

Parameters:

Optional queryObj: SQLTablesQuery
Query parameters to filter the catalog.

Returns:

from tagoio_sdk import Resources

resources = Resources()
result = resources.sql.tables({"filter": "sensor", "amount": 20})
print(result)  # { 'tables': [...], 'resources': { 'devices': [...], 'entities': [...] } }