Skip to main content

Live Query Events

A live query is a GraphQL query that Mapped keeps running for you. Whenever its result changes, Mapped publishes a live query event carrying the new result, so a webhook can push it to you. Use one to learn when sites are added to your org, when new devices are discovered, when relationships change, or anything else you can express as a query over the graph.

Event​

AttributeValue
typemapped.livequery.resultChangeNotification.v1.created
source//com.mapped/orgs/{orgId}/liveQueries/{liveQueryId}
idUnique per event, starting with LVQCH.

Payload​

FieldTypeDescription
liveQueryIdstringThe ID of the live query, the same as the last part of source.
lastResultobjectThe query's full current result: the data of the GraphQL response, without errors.
{
"lastResult": {
"sites": [
{ "id": "SITEA2yCZ58ZpJsE7hH3Sj52CP", "name": "Headquarters" },
{ "id": "SITETeZNmbxTZKbN6ArdANbyvX", "name": "Distribution Center" }
]
},
"liveQueryId": "LVQCJcMTCrz86gs8UteKroy34"
}

lastResult is the whole result, not the difference from the previous one. To find out what changed, compare it with the last result you stored for that liveQueryId.

When It Is Sent​

Mapped runs the query again whenever the graph in your org changes, for example when a connector adds devices or someone edits a place, and sends an event when the new result is different from the previous one:

  • Once right after the live query is created, with its first result.
  • After a graph change that changes the result: a value changed, or an item was added or removed.

It is not sent when:

  • The result is the same. Items that only moved within a list don't count as a change.
  • The live query is paused.
  • The query fails. The live query then reports the failure (see lastErrorDate on the LiveQuery type) and sends nothing until it succeeds again.

The query only reads the graph (places, things, points, and their relationships and properties), so a live query does not fire for time series values or for users, tokens, or connector settings.

Using It​

  • Subscribe with a filter on the live query's source, or on the type to get every live query in your org:

    @.source == '//com.mapped/orgs/ORG8Si1dkzGEYZgxrR4ZYAbCD/liveQueries/LVQCJcMTCrz86gs8UteKroy34'
  • Treat the newest result as the truth. Two changes close together can send two events that arrive in either order. Keep the result whose event time is the latest, and ignore older ones.

  • Keep results small. A very large result is slow to compute and to send. Narrow the query with filters and ask only for the fields you use.

  • Reconcile with the liveQueries query, whose lastResult is the same result the last event carried.

For a step-by-step example of a live query with a webhook, see Using a Live Query with a Webhook.