Data Queries
A text-based grammar for querying and transforming data to drive visualizations
Data queries are a purpose-built, text-based query language to retrieve, transform, and format data for visualizations.
These textual queries are very simple to automate in automations, dashboard widgets, or the API.
A data query is a collection of key:value pairs.
Every query must include a type: key:
type:worklist.subtotals
Additional keys are available depending on the type of data being requested.
A format: key prepares the response for different visualizations:
format:dictionaries
Types
| Type | Description |
|---|---|
| attachment.manifest | Iterates and filters the manifest of attachment archives (e.g. ZIP). |
| automation.invoke | Invoke a custom data.query automation. |
| calendar.availability | Aggregate any number of matching calenders to display availability over a date range by hour or day |
| calendar.events | Return events and synthesized recurring events for the given calendars grouped into days |
| classifier.prediction | Return a predicted classification for the given text using the given classifier |
| gpg.keyinfo | Return details about a PGP public key |
| metrics.timeseries | Aggregates metrics statistics over a date range |
| platform.extensions | Return a filterable and pageable list of plugin extensions for a given point |
| record.fields | Return a filterable and pageable list of fields from a record type |
| record.types | Return a filterable and pageable list of record types |
| ui.icons | Return a filterable and pageable list of icons |
| usage.behaviors | Return historical usage data for bot behaviors (e.g. uses, avg. runtime, and total runtime over time) |
| usage.snippets | Return historical usage data for snippets (e.g. uses by worker over time) |
| worklist.geo.points | Return geolocation data from worklist records |
| worklist.metrics | Return computed metrics based on worklist data (e.g. ‘average ticket first response time over the past year’) |
| worklist.records | Retrieve record dictionaries with a search query |
| worklist.series | Return series-based data from any worklist (e.g. tickets created by month by status) |
| worklist.subtotals | Run aggregate functions to categorize matching worklist records |
| worklist.xy | Plot two-dimensional data to visualize clusters or correlations |
| sample.* | Return simulated data |
| custom | Fetch custom data from a bot behavior |
Running data queries
Data queries may be utilized in several features.
Setup
As an administrator, you can test data queries from Setup » Developers » Data Query Tester.
Dashboard widgets
Data queries can be used to build visualizations on dashboards.
Bot behaviors
All bot behaviors can use the Execute » Data Query action to run a data query and retrieve the results.
This is a much simpler way to exchange information between bots and APIs.
API
Data queries can be run from the API using the /data/query endpoint.
For a GET the query should be provided in the q query parameter.
For a POST the query should be provided as text in the HTTP request body.
The results will always be in JSON format. This is now the recommended way to extract data from worklists and bots for use in other applications.
Data is returned in JSON format.