Merge pull request #78 from Esri/cs/1545-update-query-stats

changanxian · web-flow · commit 21f18d175717 · 2024-07-22T13:17:28.000-07:00
Update the sample "Query Table Statistics"
diff --git a/lib/samples/query_table_statistics/README.md b/lib/samples/query_table_statistics/README.md
@@ -0,0 +1,34 @@
+# Query table statistics
+
+Query a table to get aggregated statistics back for a specific field.
+
+![Image of query table statistics](query_table_statistics.png)
+
+## Use case
+
+For example, a county boundaries table with population information can be queried to return aggregated results for the total, average, maximum, and minimum population, rather than downloading the values for every county and calculating the statistics manually.
+
+## How to use the sample
+
+Pan and zoom to define the extent for the query. In the Settings panel, use the 'Only cities in current extent' checkbox to control whether the query includes only features in the visible extent, or use the 'Only cities greater than 5M' checkbox to filter the results to only those cities with a population greater than 5 million people. Tap the 'Get statistics' to perform the query. The query will return population-based statistics from the combined results of all features matching the query criteria.
+
+## How it works
+
+1. Create a `ServiceFeatureTable` with a URL to the feature service.
+2. Create `StatisticsQueryParameters`, and `StatisticDefinition` objects, and add to the parameters.
+3. Execute `queryStatistics` on the `ServiceFeatureTable`. Depending on the state of the two checkboxes, additional parameters are set.
+4. Display each `StatisticRecord` in the first returned `QueryStatisticsResult`.
+
+## Relevant API
+
+* QueryParameters
+* ServiceFeatureTable
+* StatisticDefinition
+* StatisticRecord
+* StatisticsQueryParameters
+* StatisticsQueryResult
+* StatisticType
+
+## Tags
+
+analysis, average, bounding geometry, filter, intersect, maximum, mean, minimum, query, spatial query, standard deviation, statistics, sum, variance
diff --git a/lib/samples/query_table_statistics/README.metadata.json b/lib/samples/query_table_statistics/README.metadata.json
@@ -2,10 +2,44 @@
     "category": "Search and Query",
     "description": "Query a table to get aggregated statistics back for a specific field.",
     "ignore": false,
-    "images": [],
-    "keywords": [],
+    "images": [
+        "query_table_statistics.png"
+    ],
+    "keywords": [
+        "analysis",
+        "average",
+        "bounding geometry",
+        "filter",
+        "intersect",
+        "maximum",
+        "mean",
+        "minimum",
+        "query",
+        "spatial query",
+        "standard deviation",
+        "statistics",
+        "sum",
+        "variance",
+        "QueryParameters",
+        "ServiceFeatureTable",
+        "StatisticDefinition",
+        "StatisticRecord",
+        "StatisticType",
+        "StatisticsQueryParameters",
+        "StatisticsQueryResult"
+    ],
     "redirect_from": [],
-    "relevant_apis": [],
-    "snippets": [],
+    "relevant_apis": [
+        "QueryParameters",
+        "ServiceFeatureTable",
+        "StatisticDefinition",
+        "StatisticRecord",
+        "StatisticType",
+        "StatisticsQueryParameters",
+        "StatisticsQueryResult"
+    ],
+    "snippets": [
+        "query_table_statistics_sample.dart"
+    ],
     "title": "Query table statistics"
 }
diff --git a/lib/samples/query_table_statistics/query_table_statistics.png b/lib/samples/query_table_statistics/query_table_statistics.png
diff --git a/lib/samples/query_table_statistics/query_table_statistics_sample.dart b/lib/samples/query_table_statistics/query_table_statistics_sample.dart
@@ -14,6 +14,8 @@
 // limitations under the License.
 //
 
+import 'dart:math';
+
 import 'package:arcgis_maps/arcgis_maps.dart';
 import 'package:flutter/material.dart';
 
@@ -29,114 +31,210 @@ class QueryTableStatisticsSample extends StatefulWidget {
 
 class _QueryTableStatisticsSampleState extends State<QueryTableStatisticsSample>
     with SampleStateSupport {
+  // Create a controller for the map view.
   final _mapViewController = ArcGISMapView.createController();
-  final _serviceFeatureTable = ServiceFeatureTable.withUri(Uri.parse(
-      'https://sampleserver6.arcgisonline.com/arcgis/rest/services/SampleWorldCities/MapServer/0'));
-  bool _onlyCitiesInCurrentExtent = true;
-  bool _onlyCitiesGreaterThan5M = true;
-  final _statisticDefinitions = List<StatisticDefinition>.empty(growable: true);
-
-  @override
-  void initState() {
-    super.initState();
-
-    for (final type in StatisticType.values) {
-      _statisticDefinitions.add(
-        StatisticDefinition(onFieldName: 'POP', statisticType: type),
-      );
-    }
-
-    final map = ArcGISMap.withBasemapStyle(BasemapStyle.arcGISTopographic);
-    final featureLayer = FeatureLayer.withFeatureTable(_serviceFeatureTable);
-    map.operationalLayers.add(featureLayer);
-
-    _mapViewController.arcGISMap = map;
-  }
+  // Create a ServiceFeatureTable from a URL.
+  final _serviceFeatureTable = ServiceFeatureTable.withUri(
+    Uri.parse(
+      'https://sampleserver6.arcgisonline.com/arcgis/rest/services/SampleWorldCities/MapServer/0',
+    ),
+  );
+  // A flag for when the map view is ready and controls can be used.
+  var _ready = false;
+  // A flag for whether to limit the query to cities within the current extent.
+  var _onlyCitiesInCurrentExtent = true;
+  // A flag for whether to limit the query to cities with population greater than 5 million.
+  var _onlyCitiesGreaterThan5M = true;
+  // A list of statistic definitions to apply to the query.
+  final _statisticDefinitions = <StatisticDefinition>[];
+  // A flag to display the query settings.
+  var _settingsVisible = false;
 
   @override
   Widget build(BuildContext context) {
     return Scaffold(
-      body: Stack(
-        alignment: Alignment.center,
-        children: [
-          ArcGISMapView(
-            controllerProvider: () => _mapViewController,
-          ),
-          Positioned(
-            width: 350,
-            height: 180,
-            bottom: 60,
-            child: DecoratedBox(
-              decoration: BoxDecoration(
-                color: Colors.white.withOpacity(0.8),
-              ),
-              child: Column(
-                mainAxisAlignment: MainAxisAlignment.center,
-                children: [
-                  SwitchListTile(
-                    title: const Text('Only cities in current extent'),
-                    value: _onlyCitiesInCurrentExtent,
-                    onChanged: (value) {
-                      setState(() => _onlyCitiesInCurrentExtent = value);
-                    },
-                  ),
-                  SwitchListTile(
-                    title: const Text('Only cities greater than 5M'),
-                    value: _onlyCitiesGreaterThan5M,
-                    onChanged: (value) {
-                      setState(() => _onlyCitiesGreaterThan5M = value);
-                    },
+      body: SafeArea(
+        top: false,
+        child: Stack(
+          children: [
+            Column(
+              children: [
+                Expanded(
+                  // Add a map view to the widget tree and set a controller.
+                  child: ArcGISMapView(
+                    controllerProvider: () => _mapViewController,
+                    onMapViewReady: onMapViewReady,
                   ),
-                  TextButton(
-                    onPressed: queryStatistics,
-                    child: const Text(
-                      'Get statistics',
+                ),
+                Row(
+                  mainAxisAlignment: MainAxisAlignment.spaceEvenly,
+                  children: [
+                    // A button to show the Settings bottom sheet.
+                    ElevatedButton(
+                      onPressed: () => setState(() => _settingsVisible = true),
+                      child: const Text('Settings'),
                     ),
-                  ),
-                ],
+                    // A button to calculate the statistics.
+                    ElevatedButton(
+                      onPressed: queryStatistics,
+                      child: const Text('Get statistics'),
+                    ),
+                  ],
+                ),
+              ],
+            ),
+            // Display a progress indicator and prevent interaction until state is ready.
+            Visibility(
+              visible: !_ready,
+              child: SizedBox.expand(
+                child: Container(
+                  color: Colors.white30,
+                  child: const Center(child: CircularProgressIndicator()),
+                ),
               ),
             ),
-          ),
-        ],
+          ],
+        ),
       ),
+      bottomSheet: _settingsVisible ? querySettings(context) : null,
     );
   }
 
+  // The build method for the query options shown in the bottom sheet.
+  Widget querySettings(BuildContext context) {
+    return Container(
+      color: Colors.white,
+      padding: EdgeInsets.fromLTRB(
+        20.0,
+        0.0,
+        20.0,
+        max(
+          20.0,
+          View.of(context).viewPadding.bottom /
+              View.of(context).devicePixelRatio,
+        ),
+      ),
+      child: Container(
+        color: Colors.white,
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Row(
+              children: [
+                Text(
+                  'Query Settings',
+                  style: Theme.of(context).textTheme.titleMedium,
+                ),
+                const Spacer(),
+                IconButton(
+                  icon: const Icon(Icons.close),
+                  onPressed: () => setState(() => _settingsVisible = false),
+                ),
+              ],
+            ),
+            Row(
+              children: [
+                Checkbox(
+                  value: _onlyCitiesInCurrentExtent,
+                  onChanged: (value) {
+                    setState(() => _onlyCitiesInCurrentExtent = value!);
+                  },
+                ),
+                const Text('Only cities in current extent'),
+              ],
+            ),
+            Row(
+              children: [
+                Checkbox(
+                  value: _onlyCitiesGreaterThan5M,
+                  onChanged: (value) {
+                    setState(() => _onlyCitiesGreaterThan5M = value!);
+                  },
+                ),
+                const Text('Only cities greater than 5M'),
+              ],
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  // Called when the map view is ready.
+  void onMapViewReady() {
+    // Add the statistic definitions for the 'POP' (Population) field.
+    for (final type in StatisticType.values) {
+      _statisticDefinitions.add(
+        StatisticDefinition(
+          onFieldName: 'POP',
+          statisticType: type,
+        ),
+      );
+    }
+    // Create a map with a topographic basemap.
+    final map = ArcGISMap.withBasemapStyle(
+      BasemapStyle.arcGISTopographic,
+    );
+    // Create a feature layer from the service feature table.
+    final featureLayer = FeatureLayer.withFeatureTable(
+      _serviceFeatureTable,
+    );
+    // Add the feature layer to the map.
+    map.operationalLayers.add(
+      featureLayer,
+    );
+    // Set the map to the map view.
+    _mapViewController.arcGISMap = map;
+    setState(() => _ready = true);
+  }
+
+  // Query statistics from the service feature table.
   void queryStatistics() async {
-    final statisticsQueryParameters =
-        StatisticsQueryParameters(statisticDefinitions: _statisticDefinitions);
+    // Create a statistics query parameters object.
+    final statisticsQueryParameters = StatisticsQueryParameters(
+      statisticDefinitions: _statisticDefinitions,
+    );
 
+    // Set the geometry and spatial relationship if the flag is true.
     if (_onlyCitiesInCurrentExtent) {
       statisticsQueryParameters.geometry = _mapViewController.visibleArea;
-
       statisticsQueryParameters.spatialRelationship =
           SpatialRelationship.intersects;
     }
-
+    // Set the where clause if the flag is true.
     if (_onlyCitiesGreaterThan5M) {
       statisticsQueryParameters.whereClause = 'POP_RANK = 1';
     }
-
+    // Query the statistics.
     final statisticsQueryResult = await _serviceFeatureTable.queryStatistics(
-        statisticsQueryParameters: statisticsQueryParameters);
-
-    final statistics = StringBuffer();
+      statisticsQueryParameters: statisticsQueryParameters,
+    );
 
+    // Prepare the statistics results for display.
+    final statistics = [];
     final records = statisticsQueryResult.statisticRecords();
     for (final record in records) {
       record.statistics.forEach((key, value) {
-        statistics.write('\n$key: $value');
+        final displayName =
+            key.toLowerCase() == 'count_pop' ? 'CITY_COUNT' : key;
+        final displayValue = key.toLowerCase() == 'count_pop'
+            ? value.toStringAsFixed(0)
+            : value.toStringAsFixed(2);
+        statistics.add('[$displayName]  $displayValue');
       });
     }
-
+    // Display the statistics in a dialog.
     if (mounted) {
       showDialog(
         context: context,
-        builder: (BuildContext context) {
+        builder: (context) {
           return AlertDialog(
-            title: const Text('Statistical Query Results'),
+            title: Text(
+              'Statistical Query Results',
+              style: Theme.of(context).textTheme.titleMedium,
+            ),
             content: Text(
-              statistics.toString(),
+              statistics.join('\n').toString(),
             ),
           );
         },
