SQL Type

SQLParam

Attributes:

key: str
Positional parameter placeholder, such as $1.
value: str
Value bound to the placeholder.

SQLCreateInfo

Attributes:

name: str
Name of the query. Required on create and replace.
query: str
TagoSQL query text. Required on create and replace.
description: Optional[str]
Human-readable description of the query.
params: Optional[List[SQLParam]]
Default positional parameters.
cache_enabled: Optional[bool]
Whether execution results are cached.
cache_ttl_seconds: Optional[int]
Cache time-to-live in seconds.
rate_limit_rpm: Optional[int]
Execution rate limit in requests per minute.
active: Optional[bool]
Whether the query is active.
tags: Optional[List[TagsObj]]
List of tags associated with the query.

SQLInfo

Attributes:

id: GenericID
Unique identifier for the query.
name: str
Name of the query.
description: Optional[str]
Human-readable description of the query.
query: str
TagoSQL query text.
params: Optional[List[SQLParam]]
Default positional parameters.
cache_enabled: Optional[bool]
Whether execution results are cached.
cache_ttl_seconds: Optional[int]
Cache time-to-live in seconds.
rate_limit_rpm: Optional[int]
Execution rate limit in requests per minute.
active: Optional[bool]
Whether the query is active.
tags: Optional[List[TagsObj]]
List of tags associated with the query.
version: int
Current stored version number.
cache_version: int
Cache generation counter, bumped when cached results are invalidated.
versions: Dict[str, Any]
Mapping of version number to stored snapshot metadata.
created_at: datetime
Date and time when the query was created.
updated_at: datetime
Date and time when the query was last updated.
session_context: bool
Read-only. True when the query text uses session functions. Never accepted as input.

SQLFilter

Attributes:

name: str
Name to filter queries by.
active: bool
Active state to filter queries by.
tags: Optional[List[TagsObj]]
Tags to filter queries by.

SQLQuery(Query)

Attributes:

fields: Optional[List[Literal[“id”, “name”, “description”, “query”, “params”, “cache_enabled”, “cache_ttl_seconds”, “rate_limit_rpm”, “active”, “tags”, “version”, “created_at”, “updated_at”]]]
List of fields to include in the query results.
filter: Optional[SQLFilter]
Filter criteria for the query.

SQLExecuteObj

Attributes:

params: Optional[List[SQLParam]]
Positional parameters overriding the saved defaults per key.
test: Optional[bool]
When True, skips the result cache entirely.
after_device: Optional[GenericID]
Device ID used to resolve session context for the execution.

SQLColumn

Attributes:

name: str
Column name.
type: Literal[“string”, “number”, “timestamp”, “boolean”, “json”]
Column data type.

SQLExecuteResult

Attributes:

columns: List[SQLColumn]
Result columns with their types.
rows: List[dict]
Result rows keyed by column name.
row_count: int
Number of rows returned.
execution_ms: int
Server-side execution time in milliseconds.
served_from_cache: bool
True when the result was served from the cache.

SQLVersionInfo

Attributes:

query: str
Query text stored in this version.
params: List[SQLParam]
Parameters stored in this version.
created_at: Optional[datetime]
Date and time when this version was stored.

SQLTableInfo

Attributes:

function: str
Virtual table family function name.
label: str
Human-readable label.
tag_form: Optional[str]
Tag form used to resolve the table.
columns: List[SQLColumn]
Typed columns exposed by the table.
dynamic: Optional[bool]
Whether the table columns are resolved dynamically.

SQLResourceItem

Attributes:

id: GenericID
Resource identifier.
name: str
Resource name.

SQLFunctionInfo

Attributes:

name: str
Function name.
kind: Literal[“aggregate”, “session”]
Function category.
args: List[str]
Argument names.
description: str
Human-readable description.
example: Optional[str]
Present only on session functions; carries the COALESCE authoring idiom.

SQLTablesResources

Attributes:

devices: List[SQLResourceItem]
Profile devices available to queries.
entities: List[SQLResourceItem]
Profile entities available to queries.

SQLTablesResult

Attributes:

tables: List[SQLTableInfo]
Virtual table families with their typed columns.
resources: SQLTablesResources
Profile devices and entities.
functions: List[SQLFunctionInfo]
Aggregate and session functions available to queries.

SQLTablesQuery

Attributes:

filter: Optional[str]
Substring filter applied to the catalog.
amount: Optional[int]
Number of items per page.
page: Optional[int]
Page number.
entity_id: Optional[GenericID]
Entity ID used to resolve one entity’s columns.