Skip to content
View on GitHubSample viewer app

Find dynamic entities from a data source that match a query.

screenshot

Use case

Developers can query a DynamicEntityDataSource to find dynamic entities that meet spatial and/or attribute criteria. The query returns a collection of dynamic entities matching the DynamicEntityQueryParameters or track IDs at the moment the query is executed. An example of this is a flight tracking app that monitors airspace near a particular airport, allowing the user to monitor flights based on different criteria such as arrival airport or flight number.

How to use the sample

Tap the "Query Flights" button and select a query to perform from the menu. Once the query is complete, a list of the resulting flights will be displayed. Tap on a flight to see its latest attributes in real-time.

How it works

  1. Create a CustomDynamicEntityDataSource to stream dynamic entity events.
  2. Create a DynamicEntityLayer with the data source and add it to the map's operational layers.
  3. Create DynamicEntityQueryParameters and set properties for the query:
    • To spatially filter results, set the geometry and spatialRelationship (defaults to Intersects).
    • To query entities with certain attribute values, set the whereClause.
    • To get entities with specific track IDs, call setTrackIds().
  4. Perform the query with DynamicEntityDataSource::queryDynamicEntitiesAsync(parameters) for combined criteria, or pass only trackIds if you want an exact track ID lookup.
  5. When complete, iterate DynamicEntityQueryResult via iterator().asList() to access returned DynamicEntity objects.
  6. Connect to DynamicEntity::dynamicEntityChanged to receive real-time attribute updates.
  7. Read the latest observation from DynamicEntityChangedInfo::receivedObservation.

Relevant API

  • DynamicEntity
  • DynamicEntityChangedInfo
  • DynamicEntityDataSource
  • DynamicEntityDataSourceInfo
  • DynamicEntityLayer
  • DynamicEntityObservation
  • DynamicEntityQueryParameters
  • DynamicEntityQueryResult

About the data

This sample uses the PHX Air Traffic JSON portal item, which is hosted on ArcGIS Online and downloaded automatically. The file contains JSON data for mock air traffic around the Phoenix Sky Harbor International Airport in Phoenix, AZ, USA. The decoded data is used to simulate dynamic entity events through a CustomDynamicEntityDataSource, which is displayed on the map with a DynamicEntityLayer.

Additional information

A dynamic entities query is performed on the most recent observation of each dynamic entity in the data source at the time the query is executed. As the dynamic entities change, they may no longer match the query parameters.

Tags

data, dynamic, entity, live, query, real-time, search, stream, track

Sample Code

CustomDynamicEntityDataSource.cppCustomDynamicEntityDataSource.cppQueryDynamicEntities.cppFlightInfoListModel.cppCustomDynamicEntityDataSource.hFlightInfoListModel.hQueryDynamicEntities.hQueryDynamicEntities.qml
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
// [WriteFile Name=QueryDynamicEntities, Category=Search]
// [Legal]
// Copyright 2026 Esri.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0

// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// [Legal]

// sample headers
#include "CustomDynamicEntityDataSource.h"

// ArcGIS Maps SDK headers
#include "Domain.h"
#include "DynamicEntityDataSource.h"
#include "DynamicEntityDataSourceInfo.h"
#include "Field.h"
#include "Point.h"
#include "ServiceTypes.h"
#include "SpatialReference.h"

// Qt headers
#include <QtConcurrent/QtConcurrent>

using namespace Esri::ArcGISRuntime;

CustomDynamicEntityDataSource::CustomDynamicEntityDataSource(const QString& fileName,
                                                             const QString& entityIdField,
                                                             const int msDelay,
                                                             QObject* parent) :
  DynamicEntityDataSource(parent),
  m_fileName(fileName),
  m_entityIdField(entityIdField),
  m_msDelay(msDelay)
{
}

CustomDynamicEntityDataSource::~CustomDynamicEntityDataSource()
{
  // The app will crash upon destruction if the asynchronous method is still running upon destruction
  m_watcher.cancel();
  m_watcher.waitForFinished();
}

// Override the virtual onLoadAsync method to define what the DynamicEntityDataSource will do upon load
QFuture<DynamicEntityDataSourceInfo*> CustomDynamicEntityDataSource::onLoadAsync()
{
  m_fields = getSchema();

  m_file.setFileName(m_fileName);

  if (m_file.open(QIODevice::ReadOnly | QIODevice::Text))
  {
    m_textStream.setDevice(&m_file);
  }

  // Create a DynamicEntityDataSourceInfo object to return
  DynamicEntityDataSourceInfo* dynamicEntityDataSourceInfo = new DynamicEntityDataSourceInfo(m_entityIdField, m_fields, this);

  // Your data may not display correctly if you do not have a spatial reference set
  dynamicEntityDataSourceInfo->setSpatialReference(SpatialReference::wgs84());

  // Return the QFuture<DynamicEntityDataSourceInfo*>
  return QtFuture::makeReadyValueFuture(dynamicEntityDataSourceInfo);
}

// Override the virtual onConnectAsync method to define what the DynamicEntityDataSource will do when the data source is connected
QFuture<void> CustomDynamicEntityDataSource::onConnectAsync()
{
  m_watcher.setFuture(QtConcurrent::run([this]()
  {
    observationProcessLoopAsync();
  }));
  return QtFuture::makeReadyVoidFuture();
}

// Override the virtual onDisconnectAsync method to define what the DynamicEntityDataSource will do when the data source is disconnected
QFuture<void> CustomDynamicEntityDataSource::onDisconnectAsync()
{
  m_watcher.cancel();
  m_watcher.waitForFinished();
  return QtFuture::makeReadyVoidFuture();
}

// This method runs asynchronously to step through the accompanying .json file and call addObservation(geometry, attributes) with each line
void CustomDynamicEntityDataSource::observationProcessLoopAsync()
{
  while (!m_textStream.atEnd() && !m_watcher.isCanceled())
  {
    const QString line = m_textStream.readLine();
    const QJsonObject jsonObject = QJsonDocument::fromJson(line.toUtf8()).object();

    // Get the observation geometry from the line
    const QJsonObject geometryObject = jsonObject.value("geometry").toObject();
    const Point point(geometryObject.value("x").toDouble(), geometryObject.value("y").toDouble(), SpatialReference::wgs84());

    // Get the observation attributes from the line
    const QVariantMap attributes = jsonObject.value("attributes").toObject().toVariantMap();

    addObservation(point, attributes);

    QThread::msleep(m_msDelay);

    if (m_textStream.atEnd())
    {
      m_textStream.seek(0);
    }
  }
}

// Schema fields that are hardcoded to match the accompanying .json data
QList<Field> CustomDynamicEntityDataSource::getSchema()
{
  return QList<Field>{Field(FieldType::Text, "aircraft", "", 8, Domain(), false, false),
                      Field(FieldType::Float64, "altitude_feet", "", 8, Domain(), false, false),
                      Field(FieldType::Text, "arrival_airport", "", 8, Domain(), false, false),
                      Field(FieldType::Text, "flight_number", "", 8, Domain(), false, false),
                      Field(FieldType::Float64, "heading", "", 8, Domain(), false, false),
                      Field(FieldType::Float64, "speed", "", 8, Domain(), false, false),
                      Field(FieldType::Text, "status", "", 8, Domain(), false, false)};
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.