Query table features

Highlight demographic data in a table joined to a feature layer.

What are table feature queries?

To access features in a table, 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 query to a feature service. To make the request, you will need the service URL or item ID.

You use table features queries to:

Access a subset of features in a table
Request features with a SQL WhereClause query
Return features in different data formats e.g. JSON, GeoJSON, and PBF
Return all or a subset of attribute fields for features
Return features without geometries

How to query table features

The steps to access and query features are:

Find the service URL for the feature layer to query.
Define the query SQL parameters (where clause).
Define the output parameters (data format).
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
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
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>

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:

Client-side cache: A response cache stored and managed by a web browser, native application, or operating system.
CDN cache: A response cache stored and managed by CDN servers worldwide (ArcGIS Platform and ArcGIS Online only). This cache is configurable.
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:

Client-side cache (if available)
CDN cache (if available)
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.

Client-side cache

A client-side cache is the response data from queries to the feature service stored in a web browser, native application, or operating system. If the cache is available, the applications use this cache first before making requests to the feature service. When using the cache, the ArcGIS Maps SDKs also check to see if the features have been updated in the feature service so it can update the local cache. A client-side cache is only used by individual applications and cannot be shared with others. When available, these are the highest-performing caches.

CDN cache

A CDN cache is the response data from queries stored on CDN servers around the world. The CDN caches the data returned from the service for requests for a length of time (cacheMaxAge) that you specify in the hosted feature layer (item) settings. The CDN cache is for feature layers with the sharing level set to Everyone (public) for ArcGIS Online and Owner (private) for ArcGIS Platform. The CDN cache is shared and can be accessed by any application that can access the service. The CDN cache is used when the client-side cache is not available. If available, these are the next highest-performing caches.

CDN caches are only available when using ArcGIS Platform (private layers) or ArcGIS Online (public layers).

Feature tile cache

A feature tile is a data structure that contains the results of a query request stored in the server. A feature tile is created when a query request contains resultType=tile or cacheHint=true. The tiles can be sent directly back to the client to satisfy a query request or stored in a feature tile cache, CDN cache, or client-cache for future use.

A feature tile cache is the response data from queries stored at the service level as one or more feature tiles. A feature service cache is used when a client application sends consistent and repeatable queries to a feature service and the service stores the results as feature tiles for future use. The ArcGIS Maps SDKs use this mechanism to ask the feature service to store query responses as feature tiles on the service so they can be used by others. The cache is managed by the feature service and automatically updated if the underlying features are edited or updated. Feature service caches are shared and available to all client applications that send the same query request. Feature tile caches are used when client-side and CDN caches are not available.

Feature tile caches are available when using ArcGIS Platform, ArcGIS Online, or ArcGIS Enterprise (object store must be configured).

URL request

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

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

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

Required parameters

Name	Description	Examples
`f`	The format of the data returned.	`f=json` `f=pjson` `f=geojson` `f=pbf` `f=html`
`token`	An 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.

Name	Description	Examples
`where`	A 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.

Output parameters

Use these parameters to define and optimize the query response.

Name	Description	Examples
`outFields`	A 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=*`.
`orderByFields`	Order 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

Name	Description	Examples
`cacheHint`	Ask 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`

Pagination parameters

Use these parameters to paginate through records that are beyond the services maxRecordCount property.

Name	Description	Examples
`resultRecordCount`	The number of records to return from a query, if not specificed the service defaults to `maxRecordCount`.	`resultRecordCount = 500`
`resultOffset`	Skip this number of records and start from the next record (that is, resultOffset + 1). The default is 0.	`resultOffset = 0`

Code examples

Query all features

To query and display features (records) in a table, you reference the layer by its URL or ID and specify which data attributes to return. In this example, a Trailheads hosted table is accessed and all of the records are displayed. To specify the fields returned, outFields is used in the query.

Steps

Get the hosted table URL and layer ID.
Add the hosted table and define the fields.
Display the fields and records.

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for KotlinArcGIS Maps SDK for SwiftArcGIS Maps SDK for .NETArcGIS Maps SDK for JavaArcGIS API for PythonArcGIS REST JS

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
        const q = trailsLayer.createQuery()
        q.where = "1=1"
        q.cacheHint = true
        q.outFields = Object.keys(outFields)

        trailsLayer.queryFeatures(q).then(loadTable)

Expand

Go to sample

SQL query for features

To search for features (records) in a table, you can query features using a SQL where clause. In the example below, a where clause is used to return parcel features from a table based on input values. Since these queries are unknown and unique based on user input they should not be cached.

Steps

Get the hosted table URL and layer ID.
Create and execute a SQL query.
Display the records.

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
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
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382

          const parcelQuery = {
            where: whereClause,
            outFields: Object.keys(outFields), // Attributes to return
            orderByFields: ["yearbuilt1 ASC", "sqftmain1 ASC"],
          }

          parcelsTable.queryFeatures(parcelQuery).then(resp => {
            document.getElementById(
              "resultCountLabel"
            ).innerHTML = `${resp.features.length} records returned`
            addToTable(resp, true)
            setLoading(false)
          })

Expand

Go to API reference

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

1
2
3
4
curl https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_parcels_table/FeatureServer/0/query? \
-d "where=yearbuilt1 >= 2019 and sqftmain1 >= 4000 and bedrooms1 <= 4 and bathrooms1 >= 3" \
-d "outFields=usetype, ain, situsfulla, yearbuilt1, sqftmain1, bedrooms1, bathrooms1" \
-d "f=json"

View in Postman

Use dark colors for code blocksCopy
{
    "objectIdFieldName": "OBJECTID",
    "uniqueIdField": {
        "name": "OBJECTID",
        "isSystemMaintained": true
    },
    "globalIdFieldName": "",
    "geometryType": "esriGeometryPolygon",
    "spatialReference": {
        "wkid": 102100,
Expand

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 features in sets of 1000 based on object id.

To learn more, visit the REST services documentation.

Steps

Get the hosted table item ID or URL and layer ID.
Set the resultRecordCount, and resultOffset parameters of the query and execute.
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
        // create initial query params
        const queryParams = {
          where: "1=1",
          outFields: Object.keys(appParams.outFields),
          orderByFields: ["FID asc"],
          returnGeometry: true,
          num: appParams.returnCount, // number of records to return
          start: appParams.currentPage, // offset for pagination
        }

        /**
         * Set current page and send query request to the server
         */
        const queryFeatures = () => {
          // set the page to retrieve
          queryParams.start = appParams.currentPage // set offset based on what page to return
          parcelsLayer.queryFeatures(queryParams).then(displayResults)
        }

Expand

Go to API Reference

REST API

cURL

HTTP

Use dark colors for code blocks

Copy

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"

Run in Postman

Use dark colors for code blocksCopy
{
    "objectIdFieldName": "FID",
    "uniqueIdField": {
        "name": "FID",
        "isSystemMaintained": true
    },
    "globalIdFieldName": "GlobalID",
    "geometryProperties": {
        "shapeAreaFieldName": "Shape__Area",
        "shapeLengthFieldName": "Shape__Length",
Expand

Join a table to a feature layer

You can combine the attributes from one dataset to another based on attribute relationships which creates new feature data. In this example, you use the JoinFeatures operation from the spatial analysis service to join the Trailheads_data hosted table to the Trailheads_locations hosted feature layer. The resulting layer displays the corresponding attribute information for trailheads.

Steps

Get the hosted table URL.
Get the feature layer URL.
Join the feature table to the feature layer.
Display the resulting layer from the join.

APIs

ArcGIS Maps SDK for JavaScriptArcGIS Maps SDK for JavaScriptArcGIS API for PythonArcGIS REST JS
Expand
Use dark colors for code blocksCopy
                const trailsResults = await trailsLayer.load().then(() => {
                    return trailsLayer.queryFeatures({
                        where: "1=1",
                        returnGeometry: true,
                        outFields: ["TRL_NAME"]
                    });
                });

                const tableResults = await tableLayer.load().then(() => {
                    return tableLayer.queryFeatures({
                        where: "1=1",
                        outFields: ["*"],
                        returnGeometry: false
                    });
                });

                const joinedAttFeatures = [];
                trailsResults.features.forEach((trailsFeature) => {
                    tableResults.features.forEach((tableFeature) => {
                        if (trailsFeature.attributes["TRL_NAME"] === tableFeature.attributes["TRL_NAME"]) {
                            trailsFeature.attributes = { ...trailsFeature.attributes, ...tableFeature.attributes };
                            joinedAttFeatures.push(trailsFeature.clone());
                        }
                    })
                });

                const joinedLayer = new FeatureLayer({
                    id: "joined-layer",
                    source: joinedAttFeatures,
                    objectIdField: "ObjectId2",
                    fields: tableLayer.fields,
                    title: "Joined Layer",
                    geometryType: "point",
                    outFields: ["*"]
                })
                map.add(joinedLayer);

                // Add layer to the feature table widget
                const featureTable = new FeatureTable({
                    view: view,
                    layer: joinedLayer,
                    container: tableDiv,
                    hiddenFields: ["OBJECTID"]
                });
Expand
Go to sample

Service requests

Request

HTTPHTTPcURL
Use dark colors for code blocksCopy
POST arcgis.com/sharing/rest/portals/self HTTP/1.1
Content-Type: application/x-www-form-urlencoded

&f=json
&token=<ACCESS_TOKEN>
View in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "helperServices": {
    // Other parameters
    "analysis": {
      "url": "https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer"
    },
    "geoenrichment": {
      "url": "https://geoenrich.arcgis.com/arcgis/rest/services/World/GeoenrichmentServer"
    }
  }
}

Request

HTTP

cURL

Use dark colors for code blocks

Copy

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

POST <ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/JoinFeatures/submitJob HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>
&targetLayer={"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads_locations/FeatureServer/0"}
&joinLayer={"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads_data/FeatureServer/0"}
&joinOperation=joinOneToOne
&attributeRelationship=["{"targetField":"TRL_NAME","operator":"equal","joinField":"TRL_NAME"}"]
&recordsToMatch={"groupByFields":"","orderByFields":"OBJECTID ASC","topCount":1}
&joinType=inner
&outputName={"serviceProperties":{"name":"Join features sql result"}}
&context={"extent":{"xmin":-9745081.305501556,"ymin":3688856.7703679274,"xmax":-7938721.45306675,"ymax":4734515.317308861,"spatialReference":{"wkid":102100,"latestWkid":3857}}}

View in Postman

Response (JSON)

Use dark colors for code blocksCopy

{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSubmitted",
  "results": {},
  "inputs": {},
  "messages": []
}
Expand

Request

HTTP

cURL

Use dark colors for code blocks

Copy

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
POST <ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/JoinFeatures/jobs/j347a8b21b5d943fbb4600772f3b2043e HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

View in Postman

Response (JSON)

Expand
Use dark colors for code blocksCopy
{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSucceeded",
  "results": {
    "outputLayer": {
      "paramUrl": "results/outputLayer"
    }
  },
  "inputs": {},
  "messages": []
}
Expand

Request

HTTP

cURL

Use dark colors for code blocks

Copy

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
POST <ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/JoinFeatures/jobs/j347a8b21b5d943fbb4600772f3b2043e/results/outputLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

View in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "paramName": "outputLayer",
  "dataType": "GPString",
  "value": {
      "url": "<RESULT_ITEM_URL>",
      "itemId": "<RESULT_ITEM_ID>"
  }
}

Tutorials

Add a feature layer

Access and display point, line, and polygon features from a feature service.

Add a vector tile layer

Access and display a vector tile layer in a map.

Add a map tile layer

Access and display a map tile layer in a map.

Style a feature layer

Use symbols and renderers to style feature layers.

Query a feature layer (spatial)

Execute a spatial query to get features from a feature layer.

Query a feature layer (SQL)

Execute a SQL query to access polygon features from a feature layer.

Edit feature data

Add, update, and delete features in a feature service.

Display a popup

Format a popup to show attributes in a feature layer.

Workflows

Create a feature service for an app

Learn how to import parcel data, create and style a feature layer, and then access the features in an app.

Create a feature layer view for an editor app

Learn how to import parcel data, create and style a feature layer view, and then access the features in an editing app.

Create a vector tile service for an app

Learn how to import parcel data, style a feature layer, and then create a vector tile service for an app.

Create a map tile service for an app

Learn how to import contour data, style a feature layer, and create a map tile service for an app.

Services

Feature service

Add, update, delete, and query feature data.

Vector tile service

Store and access vector tile data.

Map tile service

Store and access map tile data.

API support

Use Client APIs to create, manage, and access data services. The table below outlines the level of support for each API.

	Manage	Access
ArcGIS Maps SDK for JavaScript	¹
ArcGIS Maps SDK for Kotlin	¹
ArcGIS Maps SDK for Swift	¹
ArcGIS Maps SDK for Java	¹
ArcGIS Maps SDK for .NET	¹
ArcGIS Maps SDK for Qt	¹
ArcGIS API for Python
ArcGIS REST JS
Esri Leaflet	²
MapLibre GL JS	²	³
OpenLayers	²	³

Full supportPartial supportNo support

1. Use portal class and direct REST API requests
2. Access via ArcGIS REST JS
3. Requires manually setting styles for renderers

Tools

Developer dashboard

Manage API keys, service usage, and data with the ArcGIS Developers website.

ArcGIS.com

Create, manage, and share content and data with GIS tools.

Map Viewer

Create, explore, and share web maps for 2D applications.

Mapping APIs and location services

Query table features

Was this page helpful?