Query features

Client-side and server-side queries used to display and perform calculations on parcels in Santa Monica

What are feature queries?

To access features in a feature layer, you need to use the feature service query operation. To do so, you can use ArcGIS Maps SDKs, open source libraries, scripting APIs, or the REST API to make a SQL and/or spatial query to a feature service. To make the request, you will need the service URL or item ID.

You use feature queries to:

  • Access a subset of features in a feature layer
  • Request features with a SQL WhereClause query
  • Request features with a spatial query using a geometry and relationship type
  • Return features in different data formats e.g. JSON, GeoJSON, and PBF
  • Return feature geometries in different projections
  • Return all or a subset of attribute fields for features
  • Return features with or without geometries

How to query features

The steps to access and query features are:

  1. Find the service URL for the feature layer to query.
  2. Define the query SQL parameters and/or spatial parameters.
  3. Define the output parameters (data format and spatial reference).
  4. Execute the query.

Types of queries

In general, the two types of feature queries you can implement are repeatable queries and unique queries.

Repeatable query

A repeatable query is a query you send to a feature service that contains consistent and repeatable input values that multiple users will execute from an application. The values of the parameters such as geometry, SQL where clause, search text, spatial relationship operator, or a combination of them will all be the same for each request. Since the query is repeatable, the responses will be the same for the queries, and you can use cacheHint=true to ask the service to cache the results.

Below is an example of a repeatable query with a repeatable where clause:

Use dark colors for code blocksCopy
1
https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0/query?f=pbf&cacheHint=true&resultRecordCount=100&where=UseType = 'Irrigated Farm'&outFields=APN,UseType,TaxRateCity,TaxRateArea,Roll_LandValue&returnGeometry=false&token=<ACCESS_TOKEN>

Unique query

A unique query is a query you send to a feature service that contains unique input values defined by the user of an application. The values of the parameters for the geometry, SQL where clause, search text, spatial relationship operator, or a combination of them are unique and unknown. Since the queries are unique, the responses are also unique and are not automatically cached. You should not use cacheHint=true to ask the service to cache results from unique queries.

Below is an example of a unique query with a user-defined geometry:

Use dark colors for code blocksCopy
1
https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0/query?f=pbf&geometry={"rings":[[[-13228576.521843342,4033084.7250306536],[-13222485.595442941,4033084.7250306536],[-13222485.595442941,4030103.75557307],[-13228576.521843342,4030103.75557307],[-13228576.521843342,4033084.7250306536]]]}&outFields=APN,UseType,TaxRateCity,Roll_LandValue&spatialRel=esriSpatialRelIntersects&geometryType=esriGeometryPolygon&token=<ACCESS_TOKEN>

Client-side queries

The ArcGIS Maps SDKs provide an additional way to query features on the client.

A client-side query is a type of query you can perform against features stored locally on the client. To implement this query, an application needs to make an initial query to a feature service to get features, but afterward, they can perform additional client-side queries against the local features. This prevents unnecessary queries to the feature service. The ArcGIS Maps SDKs support client-side SQL and spatial queries.

Feature queries and caches

When you query and/or display features, different response caches are available to help maximize the performance and scalability of applications. A response cache is the data returned from a query request that is stored and managed so it can be reused by clients. Response caches are only beneficial to applications that make repeatable queries. Making use of response caches improves both performance and scalability allowing your application to perform well even when experiencing high load.

There are multiple levels of caches available to applications. This includes the following:

  1. Client-side cache: A response cache stored and managed by a web browser, native application, or operating system.
  2. CDN cache: A response cache stored and managed by CDN servers worldwide (ArcGIS Platform and ArcGIS Online only). This cache is configurable.
  3. Feature tile cache: A response cache stored and managed internally by the feature service.

All three levels of caches can exist at the same time. How the caches are used by an application, however, depends on the type of API you are using, the CDN cache max age settings you apply, and the parameters you include with the request.

In general, when a query request is sent to a feature service, the response caches are accessed in the following order:

  1. Client-side cache (if available)
  2. CDN cache (if available)
  3. Feature tile cache (if available)

If a cache is available, the response cache is sent back to the client immediately. If a cache isn't available, the request will look for the next level of cache that is available. If no caches are found, the query is processed by the feature service and the response is sent back to the client. If the response is cacheable, it will be stored at the appropriate caching level so it can be reused in the future.

URL request

Use dark colors for code blocksCopy
1
https://{host}/{organizationID}/ArcGIS/rest/services/{serviceName}/FeatureServer/{id}/query?{queryParameters}

Required parameters

NameDescriptionExamples
fThe format of the data returned.f=json f=pjson f=geojson f=pbf f=html
tokenAn API key or OAuth 2.0 access token. Learn how to get an access token in Security and authentication.token=<ACCESS_TOKEN>

SQL parameters

Use this parameter to define a WhereClause for a SQL query.

NameDescriptionExamples
whereA SQL clause that defines which data to return based upon attribute values. To query based upon geometry, see the geometry and spatialRel parameters. Learn more about the SQL-92 format here.

Spatial parameters

Use these parameters to define the type of spatial query.

NameDescriptionExamples
geometryThe geometry parameter is key to all spatial queries. The query result will include features that relate to the geometry parameter value according to a spatial relationship specified by the spatialRel parameter.

The value can be specified in one of 3 formats:
- Simple point syntax: geometry=<x>,<y>
- Simple envelope syntax: geometry=<xmin>,<ymin>,<xmax>,<ymax>
- Full JSON syntax: geometry={...}

To use the geometry parameter, you must also provide a geometryType parameter. If you use the simple syntax for the geometry, you should also specify the inSR parameter.
geometryTypeWhen a geometry parameter is provided, you must also specify the geometryType parameter. Valid values are:
- esriGeometryPoint
- esriGeometryMultipoint
- esriGeometryPolyline
- esriGeometryPolygon
- esriGeometryEnvelope
spatialRelDefines how the query geometry relates to features that should be returned in the query response. Valid values are:
- esriSpatialRelIntersects (default)
- esriSpatialRelWithin
- esriSpatialRelContains
- esriSpatialRelCrosses
- esriSpatialRelOverlaps
- esriSpatialRelTouches
- esriSpatialRelEnvelopeIntersects
- esriSpatialRelIndexIntersects

For example, to query for all trees in a park, pass the park outline as the geometry and use spatialRel=esriSpatialRelContains.

The most common spatial relationships typically used in a query are esriSpatialRelIntersects, esriSpatialRelWithin, and esriSpatialRelContains.

Learn more about spatial relationships here.
inSRThis specifies the spatial reference of the geometry parameter. You can specify a WKID, or full spatial reference JSON.
Common WKIDs are 4326 for GPS data (inSR=4326), and 3857 for Web Mercator data. To learn more, see Spatial references.
distanceBuffer the geometry parameter by an amount. The units of the amount are specified in the units parameter. distance and units parameters are useful to search near a point. Set the geometry to a point, and specify the distance and units.
unitsThe units for the value provided in the distance parameter. Valid values are:
- esriSRUnit_Meter
- esriSRUnit_StatuteMile
- esriSRUnit_Foot
- esriSRUnit_Kilometer
- esriSRUnit_NauticalMile
- esriSRUnit_USNauticalMile

Output parameters

Use these parameters to define and optimize the query response.

NameDescriptionExamples
outSRThe spatial reference to use for feature geometries returned in the query response. You can specify a WKID, or full spatial reference JSON. If features are being accessed to display in a map or scene, outSR typically matches the spatial reference of the map view or scene view. This avoids having to project features on the fly. Client APIs make use of outSR to improve performance of mapping applications. A common WKID is 3857 (outSR=3857), which is the spatial reference used by most basemap layers. To learn more, see Spatial references.
outFieldsA list of field names that specifies the attributes to return with any records (for example, outFields=AREANAME,ST,POP2000). The more fields you request, the larger the attributes portion of the response JSON payload and the longer it could take to download. Only request the fields you need for display or analysis. To return all fields, which can be useful during development and testing, use outFields=*.
returnGeometryWhether to return geometries with feature results. Geometries are returned by default when querying a feature layer. If features will not be displayed in a map or scene, you can pass returnGeometry=false to exclude geometries from the query response. For other methods that reduce the payload size of geometries returned in a query response, see maxAllowableOffset, geometryPrecision, and quantization parameters in the REST API documentation.
orderByFieldsOrder the records that are included in the response by specifying which fields to sort by and a sort order for each field:
- ASC - ascending order (default)
- DESC - descending
For example, orderByFields=STATE_NAME ASC, RACE DESC, GENDER.

Cache parameters

NameDescriptionExamples
cacheHintAsk the service to store the query response for later use. This should only be used when client applications send consistent and repeatable queries. Using cacheHint can significantly improve performance. See the Query a feature layer (SQL) example.cacheHint=true cacheHint=false

Code examples

Query a feature layer (SQL)

To retrieve a subset of data for a feature layer, you can query features using a SQL where clause. This example uses repeatable SQL where clauses to access a subset of parcels from a feature layer that contains 2.4 million features. Since this is a repeatable query, it also uses cacheHint so the service can store the query response and optimize the query for other clients.

Steps

  1. Create a map or scene.
  2. Get the feature layer URL.
  3. Create and execute a SQL query with parameters that are consistent.
  4. Show the features.

APIs

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for .NETArcGIS Maps SDK for KotlinArcGIS Maps SDK for SwiftArcGIS Maps SDK for JavaArcGIS Maps SDK for Qt (C++)ArcGIS API for PythonArcGIS REST JSEsri LeafletMapLibre GL JSOpenLayersCesiumJS
Expand
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
        // Get query layer and set up query
        const parcelLayer = new FeatureLayer({
          url:
            "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0",
        })

        const queryFeatureLayer = whereClause => {
          const parcelQuery = {
            where: whereClause, // Set by select element
            outFields: Object.keys(outFields), // Attributes to return
            returnGeometry: false, // don't return geometry
            cacheHint: true, // use feature tile cache
            num: 100, // limit return number
          }
          parcelLayer
            .queryFeatures(parcelQuery)
            .then(results => {
              addToTable(results)
            })
            .catch(error => {
              console.log(error.error)
            })
        }

REST API

cURLcURLHTTP
Use dark colors for code blocksCopy
1
2
3
4
5
6
curl https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0/query? \
-d "f=json" \
-d "where=UseType = 'Residential'" \
-d "resultRecordCount=1" \
-d "outFields=APN,UseType,TaxRateCity,Roll_LandValue" \
-d "cacheHint=true \

Query a feature layer (Spatial)

To retrieve a subset of data for a feature layer, you can query features using a spatial relation and a geometry. This example uses a spatial query to access a subset of parcels from a feature layer that contains 2.4 million features.

Steps

  1. Create a map or scene.
  2. Get the feature layer URL.
  3. Create and execute a spatial query with unique query parameters.
  4. Show the features.

APIs

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for .NETArcGIS Maps SDK for KotlinArcGIS Maps SDK for SwiftArcGIS Maps SDK for JavaArcGIS Maps SDK for Qt (C++)ArcGIS Maps SDK for Qt (QML)ArcGIS API for PythonArcGIS REST JSEsri LeafletMapLibre GL JSOpenLayersCesiumJS
Expand
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
        const parcelLayer = new FeatureLayer({
          url:
            "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0",
        })

        function queryFeaturelayer(geometry) {
          const parcelQuery = {
            spatialRelationship: "intersects", // Relationship operation
            geometry: geometry, // input geometry
            outFields: ["APN", "UseType", "TaxRateCity", "Roll_LandValue"], // Attributes to return
            returnGeometry: true,
          }
          parcelLayer
            .queryFeatures(parcelQuery)
            .then(results => {
              console.log("Feature count: " + results.features.length)
              displayResults(results)
            })
            .catch(error => {
              console.log(error)
            })
        }

REST API

cURLcURLHTTP
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
curl https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/LA_County_Parcels/FeatureServer/0/query? \
-d "where=1=1" \
-d "outFields=*" \
-d "f=json" \
-d "geometry = {"x":-118.807,"y":34.002,"spatialReference":{"wkid":4326}}" \
-d "geometryType=esriGeometryPoint" \
-d "spatialRel = esriSpatialRelIntersects"

Query features with paging

The maximum number of features returned by a single query to a hosted feature layer is constrained by the services maxRecordCount property. You can use pagination to return features that exceed the maxRecordCount. This example uses paged queries to return all of the features in a hosted feature layer in sets of 1000 records.

To learn more, visit the REST services documentation.

Steps

  1. Get the hosted table item ID or URL and layer ID.
  2. Set the resultRecordCount, and resultOffset parameters of the query and execute.
  3. Display the paginated records.

APIs

Expand
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
        // create initial query params
        const queryParams = {
          where: "1=1",
          outFields: Object.keys(appParams.outFields),
          orderByFields: ["FID asc"], // order by object id
          returnGeometry: true,
          num: appParams.returnCount, // resultRecordCount
          start: appParams.currentPage, // resultOffset
        }

        /**
         * Set current page and send query request to the server
         */
        const queryFeatures = () => {
          queryParams.start = appParams.currentPage // set the current offset to get the next batch of records
          parcelsLayer.queryFeatures(queryParams).then(displayResults)
        }

REST API

cURLcURLHTTP
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
curl "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_public_parcels/FeatureServer/0/query? \
-d f=json \
-d &token="{ACCESS_TOKEN}"
-d &where="1=1" \
-d &outFields="FID, ain, situsfulla, usetype" \
-d &orderByFields="FID ASC"
-d &resultRecordCount=1000
-d &resultOffset=0"