#docs #tql #overview

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.

TQL Query Reference

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.

PropertyDescription
queryTypeThe type of query, for example timeseries, topN, groupBy, funnel.
granularityThe 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

PropertyDescription
descending (optional)Whether to sort the results in descending order.

Additional Properties for Top N Queries

PropertyDescription
dimensionA DimensionSpec defining the dimension that you want the top taken for.
metricA 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

PropertyDescription
dimensionsA list of DimensionSpec objects to do the groupBy over.

Additional Properties for Funnel Queries

PropertyDescription
stepsA list of filters that form the steps of the funnel
stepNames (optional)An optional List of names for the funnel steps