TQL Query Reference
TelemetryDeck Query Language is the advanced query language for TelemetryDeck. You don't need to write all your queries by hand, but if you do, here's how.
Most queries for TelemetryDeck can be constructed using the regular Insight Editor. However, if you need to construct a query that’s not supported by the Insight Editor, or your query is more complicated and deeper than what the Insight Editor supports, you can use the TelemetryDeck Query Language (TQL) to construct your query.
You can use the TQL Query Builder to construct your query, or you can write it by hand. The minimum required properties are granularity
, dataSource
and queryType
. The following sections describe the properties of the query object.
This example timeseries query returns the number of users per week:
{
"queryType": "timeseries",
"dataSource": "telemetry-signals",
"granularity": "week",
"aggregations": [
{
"fieldName": "clientUser",
"name": "count",
"type": "thetaSketch"
}
]
}
This example groupBy query groups signals by the majorSystemVersion
dimension and aggregates them by the count
metric, resulting in the number of operating system versions:
{
"queryType": "groupBy",
"dataSource": "telemetry-signals",
"granularity": "all",
"dimensions": [
{
"dimension": "majorSystemVersion",
"outputName": "Major System Version",
"outputType": "STRING",
"type": "default"
}
],
"aggregations": [
{
"fieldName": "count",
"name": "Number of Signals",
"type": "longSum"
}
]
}
Common Properties
The following properties are common to all query types. See pages for each query type for additional properties only for those query types.
Property | Description |
---|---|
queryType | The type of query, for example timeseries, topN, groupBy, funnel. |
granularity | The granularity of the query. |
relativeIntervals (optional) | The time intervals to query, specified as relative to time of query. |
intervals (optional) | The time intervals to query, specified as absolute time intervals. |
baseFilters (optional) | A list of filters that are applied to all queries. |
filter (optional) | A filter that’s applied to the query. |
dataSource (optional) | The data source to query. Must be "telemetry-signals" . Defaults to “telemetry-signals”. |
testMode (optional, Bool) | Wether to show test test data (True ) or live data (False ). Defaults to False . More on Test Mode |
appID (optional) | If baseFilters is set to thisApp , the id for the app in question. |
limit (optional) | The maximum number of results to return. Defaults to unlimited |
sampleFactor (optional) | Include only every n-th signal in query. Possible values are 1 , 10 , 100 or 1000 . Defaults to 1 |
aggregations (optional) | A list of Aggregators to apply to the query. |
postAggregations (optional) | A list of Post-Aggregators to apply to the query. |
Additional Properties for Timeseries Queries
Property | Description |
---|---|
descending (optional) | Whether to sort the results in descending order. |
Additional Properties for Top N Queries
Property | Description |
---|---|
dimension | A DimensionSpec defining the dimension that you want the top taken for. |
metric | A TopNMetricSpec object specifying the metric to sort by for the top list. |
threshold (optional) | An integer defining the N in the topN (how many results you want in the top list). |
Additional Properties for Group By Queries
Property | Description |
---|---|
dimensions | A list of DimensionSpec objects to do the groupBy over. |
Additional Properties for Funnel Queries
Property | Description |
---|---|
steps | A list of filters that form the steps of the funnel |
stepNames (optional) | An optional List of names for the funnel steps |