Overview
The GraphQL API combines both real-time and historical information from the MQTT data-source and TimescaleDB. It is also possible to combine both data-sources in a single query. For example you could query real-time entity data from the MQTT data-source while also querying object class meta-data for each entity from the database.
Example Query
A GraphQL query as described before could look like this:
subscription {
entityData(locationId: 1, intervalMs: 1000) {
# this information is streamed from the MQTT broker
trackingId
time
sourceName
velocityMs
data
lat
long
# this information is internally queried from the class table
class {
id
name
}
}
}
The diagram below shows, where and how the data for the previous query is sourced from.
To execute the query, you can use the GraphiQL IDE. For using the syntax: Learn how to fetch data from a GraphQL server.
Historical Trajectories and Full Entity Data
For historical entities, select trajectory to retrieve smoothed trajectory points, or entityData to retrieve raw measurements and their additional fields. Coordinates in coordinateLongLat are ordered as longitude, latitude.
The following query selects an entity by UUID within a time range. It always returns its trajectory and only loads the raw measurements when includeFullData is true:
query EntityDetails(
$locationId: Int!
$entityId: UUID!
$after: DateTime!
$before: DateTime!
$includeFullData: Boolean! = false
) {
entities(
locationId: $locationId
ids: [$entityId]
after: $after
before: $before
) {
nodes {
id
trajectory {
time
coordinateLongLat
}
entityData @include(if: $includeFullData) {
time
coordinateLongLat
heading
velocityMs
accelerationMs
objectLength
objectWidth
objectHeight
data
}
}
}
}
includeFullData is a variable defined by this query and used by the @include directive. The frontend uses this approach for Copy full data in historical entity popups. Request raw measurements when you need them to reduce the response size for ordinary trajectory queries.
The outer after and before arguments select entities. To restrict the returned points themselves, also pass after and before to trajectory or entityData; both fields accept last to limit the number of returned points. API speed fields such as velocityMs remain in metres per second, regardless of the display unit selected in the frontend.
