Skip to content

Query dynamic entities

View inMAUIWPFWinUIView on GitHubSample viewer app

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

Image of Query Dynamic Entities

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 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 DynamicEntityDataSource to stream dynamic entity events.
  2. Create a DynamicEntityLayer using the data source and add it to the map's operational layers.
  3. Create DynamicEntityQueryParameters and set its properties to specify the parameters for the query:
    1. To spatially filter results, set the geometry and spatialRelationship. The spatial relationship is intersects by default.
    2. To query entities with certain attribute values, set the whereClause.
    3. To get entities with specific track IDs, modify the trackIDs collection.
  4. To perform a dynamic entities query, call DynamicEntityDataSource.QueryDynamicEntitiesAsync() passing in the parameters.
  5. When complete, iterate through the returned collection of DynamicEntity objects from the result.
  6. Use the DynamicEntity.DynamicEntityChanged event to get real-time updates when entity attributes change.
  7. Get the new observation from the resulting DynamicEntityChangedEventArgs using the ReceivedObservation property to update the UI with current information.

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

QueryDynamicEntities.xaml.csQueryDynamicEntities.xaml.csQueryDynamicEntities.xamlFlightInfo.csCustomStreamService.cs
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
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
// Copyright 2025 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.

using ArcGIS.Samples.Managers;
using Esri.ArcGISRuntime.ArcGISServices;
using Esri.ArcGISRuntime.Data;
using Esri.ArcGISRuntime.Geometry;
using Esri.ArcGISRuntime.Mapping;
using Esri.ArcGISRuntime.Mapping.Labeling;
using Esri.ArcGISRuntime.RealTime;
using Esri.ArcGISRuntime.Symbology;
using Esri.ArcGISRuntime.UI;
using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Linq;
using System.Threading.Tasks;
using System.Windows;
using System.Windows.Controls;

namespace ArcGIS.WPF.Samples.QueryDynamicEntities
{
    [ArcGIS.Samples.Shared.Attributes.Sample(
        name: "Query dynamic entities",
        category: "Search",
        description: "Find dynamic entities from a data source that match a query.",
        instructions: "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.",
        tags: new[] { "data", "dynamic", "entity", "live", "query", "real-time", "search", "stream", "track" })]
    [ArcGIS.Samples.Shared.Attributes.OfflineData("c78e297e99ad4572a48cdcd0b54bed30")]
    public partial class QueryDynamicEntities
    {
        private CustomStreamService _dynamicEntityDataSource;
        private DynamicEntityLayer _dynamicEntityLayer;
        private GraphicsOverlay _bufferGraphicsOverlay;
        private Esri.ArcGISRuntime.Geometry.Geometry _phoenixAirportBuffer;
        private ObservableCollection<FlightInfo> _queryResults;
        private readonly MapPoint _phoenixAirport = new MapPoint(-112.0101, 33.4352, SpatialReferences.Wgs84);

        public QueryDynamicEntities()
        {
            InitializeComponent();
            _ = Initialize();
        }

        // Sets up the map, graphics overlay, and data source for flight tracking.
        private async Task Initialize()
        {
            try
            {
                // Create the map with a basemap and initial viewpoint.
                MyMapView.Map = new Map(BasemapStyle.ArcGISTopographic);
                MyMapView.SetViewpoint(new Viewpoint(_phoenixAirport, 400000));

                // Create a graphics overlay for the airport buffer.
                _bufferGraphicsOverlay = new GraphicsOverlay();
                MyMapView.GraphicsOverlays.Add(_bufferGraphicsOverlay);

                // Create a 15-mile geodetic buffer around Phoenix Airport (PHX).
                _phoenixAirportBuffer = GeometryEngine.BufferGeodetic(
                    _phoenixAirport, 15, LinearUnits.Miles, double.NaN, GeodeticCurveType.Geodesic);

                // Create a semi-transparent fill symbol for the buffer and add it to the overlay.
                var bufferSymbol = new SimpleFillSymbol(
                    SimpleFillSymbolStyle.Solid,
                    System.Drawing.Color.FromArgb(40, 255, 0, 0),
                    new SimpleLineSymbol(SimpleLineSymbolStyle.Solid, System.Drawing.Color.Black, 1));

                // Add the buffer graphic to the overlay and hide it initially.
                _bufferGraphicsOverlay.Graphics.Add(new Graphic(_phoenixAirportBuffer, bufferSymbol));
                _bufferGraphicsOverlay.IsVisible = false;

                // Initialize the collection for query results and bind it to the results list.
                _queryResults = new ObservableCollection<FlightInfo>();
                ResultsList.ItemsSource = _queryResults;

                // Hide the results panel and flight number dialog initially.
                ResultsPanel.Visibility = Visibility.Collapsed;
                FlightNumberDialog.Visibility = Visibility.Collapsed;

                // Set up the dynamic entity data source and layer.
                await SetupDynamicEntityDataSource();
            }
            catch (Exception ex)
            {
                MessageBox.Show($"Error initializing sample: {ex.Message}", "Error",
                    MessageBoxButton.OK, MessageBoxImage.Error);
            }
        }

        // Creates and configures the dynamic entity data source and layer for real-time flight tracking.
        private async Task SetupDynamicEntityDataSource()
        {
            try
            {
                // Define the fields for the dynamic entity data source.
                var fields = new List<Field>
                {
                    new Field(FieldType.Text, "flight_number", "", 50),
                    new Field(FieldType.Text, "aircraft", "", 50),
                    new Field(FieldType.Float64, "altitude_feet", "", 0),
                    new Field(FieldType.Text, "arrival_airport", "", 10),
                    new Field(FieldType.Float64, "heading", "", 0),
                    new Field(FieldType.Float64, "speed", "", 0),
                    new Field(FieldType.Text, "status", "", 50)
                };

                var dataSourceInfo = new DynamicEntityDataSourceInfo("flight_number", fields)
                {
                    SpatialReference = SpatialReferences.Wgs84
                };

                // Get the path to the flight data JSON file.
                string dataPath = DataManager.GetDataFolder("c78e297e99ad4572a48cdcd0b54bed30", "phx_air_traffic.json");
                _dynamicEntityDataSource = new CustomStreamService(dataSourceInfo, dataPath, TimeSpan.FromMilliseconds(100));

                // Create and configure the dynamic entity layer.
                _dynamicEntityLayer = new DynamicEntityLayer(_dynamicEntityDataSource)
                {
                    TrackDisplayProperties =
                    {
                        ShowPreviousObservations = true,
                        ShowTrackLine = true,
                        MaximumObservations = 20
                    }
                };

                // Define a simple airplane symbol for the dynamic entities.
                var labelDefinition = new LabelDefinition(
                    new SimpleLabelExpression("[flight_number]"),
                    new TextSymbol
                    {
                        Color = System.Drawing.Color.Red,
                        Size = 12,
                        HaloColor = System.Drawing.Color.White,
                        HaloWidth = 2
                    })
                {
                    Placement = LabelingPlacement.PointAboveCenter
                };

                // Create a simple renderer with an airplane symbol.
                _dynamicEntityLayer.LabelDefinitions.Add(labelDefinition);
                _dynamicEntityLayer.LabelsEnabled = true;
                MyMapView.Map.OperationalLayers.Add(_dynamicEntityLayer);

                // Load the dynamic entity layer.
                await _dynamicEntityDataSource.ConnectAsync();
            }
            catch (Exception ex)
            {
                MessageBox.Show($"Error setting up data source: {ex.Message}", "Error",
                    MessageBoxButton.OK, MessageBoxImage.Error);
            }
        }

        // Handles query selection from dropdown and initiates appropriate query type.
        private async void OnQuerySelectionChanged(object sender, SelectionChangedEventArgs e)
        {
            var selectedItem = QueryDropdown.SelectedItem as ComboBoxItem;
            if (selectedItem == null)
                return;

            // Determine the query type based on the selected item's tag.
            var queryType = selectedItem.Tag as string;
            if (string.IsNullOrEmpty(queryType))
                return;

            // If querying by track ID, show the flight number input dialog. For other query types, perform the query directly.
            if (queryType == "QueryTrackId")
            {
                FlightNumberDialog.Visibility = Visibility.Visible;
                FlightNumberInput.Focus();
                FlightNumberInput.SelectAll();
            }
            else
            {
                await PerformQuery(queryType);
            }
        }

        // Processes flight number input and executes track ID query.
        private async void OnFlightNumberQuery(object sender, RoutedEventArgs e)
        {
            var flightNumber = FlightNumberInput.Text?.Trim();
            if (string.IsNullOrWhiteSpace(flightNumber))
            {
                MessageBox.Show("Enter a flight number.", "Input Required",
                    MessageBoxButton.OK, MessageBoxImage.Information);
                return;
            }

            FlightNumberDialog.Visibility = Visibility.Collapsed;
            await PerformQuery("QueryTrackId", flightNumber);
            FlightNumberInput.Clear();
        }

        // Cancels flight number input and returns to query selection.
        private void OnFlightNumberCancel(object sender, RoutedEventArgs e)
        {
            FlightNumberDialog.Visibility = Visibility.Collapsed;
            FlightNumberInput.Clear();
            QueryDropdown.SelectedIndex = -1;
        }

        // Executes the specified query type against the dynamic entity data source.
        private async Task PerformQuery(string queryType, string flightNumber = null)
        {
            try
            {
                _queryResults.Clear();

                if (_dynamicEntityLayer != null)
                {
                    _dynamicEntityLayer.ClearSelection();
                }

                _bufferGraphicsOverlay.IsVisible = false;

                if (_dynamicEntityDataSource?.ConnectionStatus != ConnectionStatus.Connected)
                {
                    MessageBox.Show("Data source is not connected. Please wait for the data to load.", "Not Ready",
                        MessageBoxButton.OK, MessageBoxImage.Information);
                    return;
                }

                // Set up query parameters based on the selected query type.
                var queryParameters = new DynamicEntityQueryParameters();

                switch (queryType)
                {
                    // Query for entities within the Phoenix airport buffer.
                    case "QueryGeometry":
                        queryParameters.Geometry = _phoenixAirportBuffer;
                        queryParameters.SpatialRelationship = SpatialRelationship.Intersects;
                        _bufferGraphicsOverlay.IsVisible = true;
                        ResultsDescription.Text = "Flights within 15 miles of PHX";
                        break;

                    // Query for entities with specific attributes (status and arrival airport).
                    case "QueryAttributes":
                        queryParameters.WhereClause = "status = 'In flight' AND arrival_airport = 'PHX'";
                        ResultsDescription.Text = "Flights arriving in PHX";
                        break;

                    // Query for a specific entity by its track ID (flight number).
                    case "QueryTrackId":
                        if (!string.IsNullOrEmpty(flightNumber))
                        {
                            queryParameters.TrackIds.Add(flightNumber);
                            ResultsDescription.Text = $"Flight {flightNumber}";
                        }
                        break;

                    default:
                        return;
                }

                IEnumerable<DynamicEntity> results = null;

                // Execute the query against the data source.
                if (_dynamicEntityLayer?.DataSource != null)
                {
                    results = await _dynamicEntityLayer.DataSource.QueryDynamicEntitiesAsync(queryParameters);
                }

                results = results ?? Enumerable.Empty<DynamicEntity>();

                // Process and display the query results.
                if (results.Any())
                {
                    foreach (var entity in results)
                    {
                        if (entity != null)
                        {
                            var flightNum = entity.Attributes["flight_number"]?.ToString();
                            if (!string.IsNullOrEmpty(flightNum))
                            {
                                _dynamicEntityLayer.SelectDynamicEntity(entity);
                                var flightInfo = new FlightInfo(entity);
                                _queryResults.Add(flightInfo);
                            }
                        }
                    }
                }

                ResultsPanel.Visibility = Visibility.Visible;

                if (!_queryResults.Any())
                {
                    MessageBox.Show("No flights currently match the criteria, but the list will update as flights enter or leave the area.",
                        "Live Tracking Active", MessageBoxButton.OK, MessageBoxImage.Information);
                }
            }
            catch (Exception ex)
            {
                MessageBox.Show($"Query failed: {ex.Message}", "Error",
                    MessageBoxButton.OK, MessageBoxImage.Error);
                System.Diagnostics.Debug.WriteLine($"Query exception: {ex}");
            }
        }

        // Centers the map view on the selected flight's current position.
        private void OnResultSelectionChanged(object sender, SelectionChangedEventArgs e)
        {
            if (ResultsList.SelectedItem is FlightInfo flight && flight.Entity != null)
            {
                var latestObs = flight.Entity.GetLatestObservation();
                if (latestObs?.Geometry is MapPoint point)
                {
                    _ = MyMapView.SetViewpointCenterAsync(point, 50000);
                }
            }
        }

        // Closes the results panel and resets the UI to the initial state.
        private void OnCloseResults(object sender, RoutedEventArgs e)
        {
            ResultsPanel.Visibility = Visibility.Collapsed;

            _queryResults.Clear();

            if (_dynamicEntityLayer != null)
            {
                _dynamicEntityLayer.ClearSelection();
            }

            _bufferGraphicsOverlay.IsVisible = false;
            QueryDropdown.SelectedIndex = -1;
        }
    }
}

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