Query (Feature Service)

URL:
https://<root>/<serviceName>/FeatureServer/query
Methods:
GET
Required Capability:
Query
Version Introduced:
10.1

Description

The query operation queries a feature service resource and returns either a feature set for each layer in the query, a count of features for each layer (if returnCountOnly is set to true ), or an array of feature IDs for each layer in the query (if returnIdsOnly is set to true ).

While there is a limit to the number of features included in the response (see the maxRecordCount property of the feature service), there is no limit to the number of object IDs returned in the ID array response. Clients can exploit this to get all the query conforming object IDs by specifying returnIdsOnly=true and subsequently requesting feature sets for subsets of object IDs.

In the feature set response, the layer features include their geometries. The records for tables do not.

You can provide arguments to the query operation as query parameters defined in the parameters table below.

New at 11.0

At this release, feature services can be published from a Google BigQuery data source using ArcGIS Pro 3.0 or later.

New at 10.9

A new parameter, timeReferenceUnknownClient , has been added at 10.9. Setting timeReferenceUnknownClient as true indicates that the client is capable of working with date field data values that are not in UTC. For more information on this parameter, see the Request parameters table below.

New at 10.6.1

Added query options for multipatch data with stripMaterials , embedMaterials , and externalizeTextures .

New at 10.5

The feature service layer Query operation supports the returnTrueCurves , historicMoment , and sqlFormat parameters.

New at 10.1 SP1

The Feature Service Query operation supports spatialRel and time parameters. The Feature Service Query operation supports a new JSON representation of the layerDefs parameter with an option to specify output fields.

Request parameters

ParameterDetails

layerDefs

Allows you to filter the features of individual layers in the query by specifying definition expressions (WHERE clauses) for those layers. A definition expression for a layer that is published with the service will always be honored. For more information on WHERE clauses, see the SQL 92 WHERE clause section below.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
//Simple syntax. Layer IDs are returned by the feature service resource
layerId1:layerDef1;layerId2:layerDef2

//JSON representation for Layer Definitions. Layer IDs are returned by the feature service resource
{ "<layerId1>" : "<layerDef1>" , "<layerId2>" : "<layerDef2>" }

//JSON representation of a layer definition to specify output fields. Layer IDs are returned by the feature service resource
[{ "layerId" : <layerId1>,"where": "<where clause>", "outfields": "<field1>,<field2>"},{"layerId" : <layerId2>,"where": "<where clause>", "outfields": "<field1>,<field2>"}]

Example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
//Simple example
0:POP2000 > 1000000;5:AREA > 100000

//JSON representation for Layer Definitions
{"0":"POP2000 > 1000000","5":"AREA > 100000"}

//JSON representation of a layer definition to specify output fields
[{"layerId" : 0, "where" : "OBJECTID<100", "outFields" : "*"}, {"layerId" : 1, "where" : "OBJECTID<323", "outFields" : "OBJECTID,CREATOR"}]

geometry

The geometry to apply as the spatial filter. The structure of the geometry is the same as the structure of the JSON geometry objects returned by the ArcGIS REST API. In addition to the JSON structures, you can specify the geometry of envelopes and points with a simple comma-separated syntax.

Syntax:

  • JSON structures: geometryType=<geometryType>&geometry={ geometry}
  • Envelope simple syntax: geometryType=esriGeometryEnvelope&geometry=<xmin>,<ymin>,<xmax>,<ymax>
  • Point simple syntax: geometryType=esriGeometryPoint&geometry=<x>,<y>

Examples:

  • geometryType=esriGeometryEnvelope&geometry={xmin: -104, ymin: 35.6, xmax: -94.32, ymax: 41}
  • geometryType=esriGeometryEnvelope&geometry=-104,35.6,-94.32,41
  • geometryType=esriGeometryPoint&geometry=-104,35.6

geometryType

The type of geometry specified by the geometry parameter. The geometry type can be an envelope, a point, a line, or a polygon. The default geometry type is an envelope.

Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope

inSR

The spatial reference of the input geometry .

The spatial reference can be specified as either a well-known ID or a spatial reference JSON object.

If inSR is not specified, the geometry is assumed to be in the spatial reference of the map.

spatialRel

The spatial relationship to be applied to the input geometry while performing the query. The supported spatial relationships include intersects, contains, envelope intersects, within, and so on. The default spatial relationship is intersects (esriSpatialRelIntersects ).

Values: esriSpatialRelIntersects | esriSpatialRelContains | esriSpatialRelCrosses | esriSpatialRelEnvelopeIntersects | esriSpatialRelIndexIntersects | esriSpatialRelOverlaps | esriSpatialRelTouches | esriSpatialRelWithin | esriSpatialRelRelation

time

The time instant or the time extent to query.

Time instant

Syntax: time=<timeInstant>

Example: time=1199145600000 (1 Jan 2008 00:00:00 GMT)

Time extent

Syntax: time=<startTime>, <endTime>

Example: time=1199145600000, 1230768000000 (1 Jan 2008 00:00:00 GMT to 1 Jan 2009 00:00:00 GMT)

A null value specified for start time or end time will represent infinity for start or end time, respectively. Example: time=null, 1230768000000

outSR

The spatial reference of the returned geometry. The spatial reference can be specified as either a well-known ID or as a spatial reference JSON object. If outSR is not specified, the geometry is returned in the spatial reference of the service.

gdbVersion

The geodatabase version to query. This parameter applies only if the hasVersionedData property of the service and the isDataVersioned property of the layers queried are true .

If gdbVersion is not specified, the query will apply to the published map’s version.

Syntax: gdbVersion=<version>

Example: gdbVersion=SDE.DEFAULT

historicMoment

The historic moment to query. This option was added at 10.5 and works with ArcGIS Server services only. This parameter applies only if the supportsQueryWithHistoricMoment property of the layers being queried is set to true . This setting is provided in the layer resource. If historicMoment is not specified, the query will apply to the current features.

Syntax

Use dark colors for code blocksCopy
1
historicMoment=<Epoch time in milliseconds>

Example

Use dark colors for code blocksCopy
1
historicMoment=1199145600000

returnGeometry

If true , the result includes the geometry associated with each feature returned. The default is true .

Values: true | false

maxAllowableOffset

This option can be used to specify the maxAllowableOffset to be used for generalizing geometries returned by the query operation. The maxAllowableOffset is in the units of the outSR . If outSR is not specified, maxAllowableOffset is assumed to be in the unit of the spatial reference of the map.

Example

Use dark colors for code blocksCopy
1
maxAllowableOffset=2

returnIdsOnly

If true , the response only includes an array of object IDs for each layer. Otherwise, the response is a feature set. The default is false .

While there is a limit to the number of features included in the feature set response, there is no limit to the number of object IDs returned in the ID array response. Clients can exploit this to get all the query conforming object IDs by specifying returnIdsOnly as true and subsequently requesting feature sets for subsets of object IDs.

Values: true | false

returnCountOnly

If true , the response only includes the count (number of features/records) that would be returned by a query. Otherwise, the response is a feature set. The default is false .

Values: true | false

returnZ

If true , z-values are included in the results if the features have z-values. Otherwise, z-values are not returned. The default is false . This parameter only applies if returnGeometry is true and at least one of the layer's hasZ properties is true .

Values: true | false

returnM

If true , m-values are included in the results if the features have m-values. Otherwise, m-values are not returned. The default is false . This parameter only applies if returnGeometry is true and at least one of the layer's hasM properties is true .

Values: true | false

geometryPrecision

The number of decimal places in the response geometries returned by the query operation. This applies to x- and y-values only (not m- or z-values).

Use dark colors for code blocksCopy
1
geometryPrecision=3

multipatchOption

How the geometry of a multipatch feature will be returned. This parameter only applies if the layers in the service have the esriGeometryMultipatch geometry type. When set to xyFootprint , the x,y footprint of each multipatch geometry will be returned in the result. When set to stripMaterials , the multipatch geometry will be returned without materials (for example, colors and textures). When set as embedMaterials , the multipatch geometry will be returned with materials embedded in it. If set to externalizeTextures , the multipatch geometry will be returned with materials, but the textures will be returned by reference.

Values: xyFootprint | stripMaterials | embedMaterials | externalizeTextures

returnTrueCurves

(Optional)

This option was added at 10.5. When set to true , the query returns true curves in output geometries. When set to false , curves are converted to densified polylines or polygons. The default value is false .

Values: true | false

sqlFormat

The sqlFormat parameter can be either standard SQL-92 standard or it can use the native SQL of the underlying data store native . The default is none , which means the sqlFormat depends on the useStandardizedQuery parameter.

Values: none | standard | native

timeReferenceUnknownClient

Setting timeReferenceUnknownClient as true indicates that the client is capable of working with data values that are not in UTC. If its not set to true , and the service layer's datesInUnknownTimeZone property is true , then an error is returned. The default is false

Its possible to define a service's time zone of date fields as unknown. Setting the time zone as unknown means that date values will be returned as-is from the database, rather than as date values in UTC. Non-hosted feature services can be set to use an unknown time zone using ArcGIS Server Manager. Setting the time zones to unknown also sets the datesInUnknownTimeZone layer property as true . Currently, hosted feature services do not support this setting. This setting does not apply to editor tracking date fields which are stored and returned in UTC even when the time zone is set to unknown.

Most clients released prior to ArcGIS Enterprise 10.9 will not be able to work with feature services that have an unknown time setting. The timeReferenceUnknownClient parameter prevents these clients from working with the service in order to avoid problems.. Setting this parameter to true indicates that the client is capable of working with unknown date values that are not in UTC.

Value: true | false

f

The response format. The default response format is html .

Values: html | json (default, when returnIdsOnly=false and returnCountOnly=false )

Values: html | json (when returnIdsOnly=true or returnCountOnly=true )

SQL 92 WHERE clause

SQL-92 WHERE clause syntax on the fields in the layer is supported for most data sources. Some data sources have restrictions on what is supported. Hosted feature services in ArcGIS Enterprise running on a spatiotemporal data source have restrictions on what is supported; they only support a subset of SQL-92. Here is a list of supported SQL 92 with spatiotemporal based feature services:

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
<COLUMN | LITERAL> '<=' | '>=' | '<' | '>' | '=' | '<>' <COLUMN | LITERAL>
<BOOLEAN EXPRESSION> AND | OR <BOOLEAN EXPRESSION>
NOT <BOOLEAN EXPRESSION>
<COLUMN> IS [ NOT ] NULL
<COLUMN> [ NOT ] LIKE <STRING>
<COLUMN> [ NOT ] IN ( <LITERAL, <LITERAL>, ... )
<COLUMN> [ NOT ] BETWEEN <COLUMN | LITERAL> AND <COLUMN | LITERAL>

Examples

Use dark colors for code blocksCopy
1
2
3
where=POP2000 > 350000

where=CITY_NAME = 'Barrington'

Date-Time Queries

In general, the dateFieldsTimeReference property of the feature service layer identifies the time zone that all dates are stored in. The exception cases involve editor tracking date fields and time aware layer time zones.

When you are working with your data, you need to consider the time zone of the fields that you are working with. If you are querying a date type field and dateFieldsTimeReference is set to a specific time zone, make sure your WHERE clause issues the time in that specific time zone. For example, if you want to return all the records that match 1:00 p.m. on February 9, 2015, Pacific standard time, your WHERE clause would be as follows:

Querying records in PST

Use dark colors for code blocksCopy
1
where=pacific_time_date_field = TIMESTAMP '2015-02-09 13:00:00'

However, it is possible to have up to three different time zones defined on your service. If your query includes dates from the editor tracking fields or the time aware fields, you need to make sure you submit the query in their respective time zones. The time zones for these fields can be found in the properties mentioned above. If the dateFieldsTimeReference is null the data is assumed to be in UTC, and if it is Unknown the time zone is assumed to be undefined. The example below demonstrates how to query three date fields that have three different times zones. When querying fields in different time zones, you need to make sure the time you use corresponds with the time zone of the date field. There is a date field in PST, one in EST, and the editor tracking field created_date in UTC:

Querying records in three different time zones

Use dark colors for code blocksCopy
1
where = (DateTime_PST = TIMESTAMP '2012-01-01 15:20:00' AND (DateTime_EST = TIMESTAMP '2012-01-01 18:20:00' AND created_date = TIMESTAMP '2012-01-01 22:20:00')

Although you issue local time in your WHERE clause, the query operation always returns date values in UTC. You can set the date fields time zone, which shows up in the dateFieldsTimeReference property of the feature service layer either during publishing or in the ArcGIS Server Manager after publishing. In the Server Manager, navigate to service you wish to edit and click on the Parameters tab to update the time zone information. If the dateFieldsTimeReference property is not set, it will show up as null and the data will be assumed to be in UTC. In this case make sure you issue your WHERE clause in UTC.

As of ArcGIS Pro 3.1 and ArcGIS Enterprise 10.9, there is a new option when defining the time zone during publishing. If you don't want to define a time zone at all (not even UTC), you can set it to Unknown. Using the Unknown time zone makes it so that there is no translation done when the query operation submits and returns date values, they are stored and returned as is. This is particularly useful if you have data which spans multiple time zones.

SQL Format

The table summarizes the sqlFormat parameter and what you can expect from the query API.

sqlFormat valueuseStandardizedQuery=trueuseStandardizedQuery=false

standard (sql'92)

Yes

Yes

native (native DBMS sql)

Not supported

Yes

none

Only sql'92 (means standard)

Only DBMS native SQL (native)

Example usage

Below is a sample request URL used to demonstrate how to query layers with the IDs of 0 and 1:

Use dark colors for code blocksCopy
1
https://machine.domain.com/webadaptor/rest/services/PoolPermits/FeatureServer/query?layerDefs={"0":"Has_Pool=1 AND Pool_Permit=1","1":"Has_Pool=1 AND Pool_Permit=1"}&returnGeometry=true&f=html

JSON Response syntax examples

Example one

The syntax example below demonstrates the structure of the response returned by query when returnCountOnly is false :

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
{
  "layers": [
    {
      "id": <layerId1>,
      "objectIdFieldName": <fieldName>,
      "globalIdFieldName": <fieldName>,
      "geometryType": "<geometryType>", //for layers only
      "spatialReference": <spatialReference>, //for layers only
      "hasZ": <true|false>,
      "hasM": <true|false>,
      "fields": [
        {
          "name": "<fieldName1>",
          "type": "<fieldType1>",
          "alias": "<fieldAlias1>",
          "length": "<length1>"
        },
        {
          "name": "<fieldName2>",
          "type": "<fieldType2>",
          "alias": "<fieldAlias2>",
          "length": "<length2>"
        }
      ],
      "features": [
        <feature1>,
        <feature2>
      ]
    },
    {
      "id": <layerId2>,
      "objectIdFieldName": <fieldName>,
      "globalIdFieldName": <fieldName>,
      "geometryType": "<geometryType>", //for layers only
      "spatialReference": <spatialReference>, //for layers only
      "hasZ": <true|false>,
      "hasM": <true|false>,
      "fields": [
        {
          "name": "<fieldName1>",
          "type": "<fieldType1>",
          "alias": "<fieldAlias1>",
          "length": "<length1>"
        },
        {
          "name": "<fieldName2>",
          "type": "<fieldType2>",
          "alias": "<fieldAlias2>",
          "length": "<length2>"
        }
      ],
      "features": [
        <feature1>,
        <feature2>
      ]
    }
  ]
}

Example two

The syntax example below demonstrates the structure of the response returned by query when returnCountOnly is true .

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
{
  "layers": [
    {
      "id": <layerId1>,
      "count": <count>
    },
    {
      "id": <layerId2>,
      "count": <count>
    }
  ]
}

Example three

The syntax example below demonstrates the structure of the response returned by query when returnIdsOnly is true .

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
{
  "layers":[
    {
      "id": <layerId1>,
      "objectIdFieldName": <objectIdFieldName>,
      "objectIds": [
        <objectId1>,
        <objectId2>,
        <objectId3>
      ]
    },
    {
      "id": <layerId2>,
      "objectIdFieldName": <objectIdFieldName>,
      "objectIds": [
        <objectId1>,
        <objectId2>,
        <objectId3>
      ]
    }
  ]
}

JSON Response examples

Example one

The response below demonstrates the response returned by query when returnIdsOnly is false and returnCountOnly is false .

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
{
  "layers": [
    {
      "id": 0,
      "objectIdFieldName": "OBJECTID",
      "globalIdFieldName": "",
      "geometryType": "esriGeometryPoint",
      "spatialReference": {
        "wkid": 4326,
        "latestWkid": 4326
      },
      "fields": [
        {
          "name": "OBJECTID",
          "type": "esriFieldTypeOID",
          "alias": "OBJECTID",
          "sqlType": "sqlTypeOther",
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "CITY_FIPS",
          "type": "esriFieldTypeString",
          "alias": "CITY_FIPS",
          "sqlType": "sqlTypeOther",
          "length": 5,
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "CITY_NAME",
          "type": "esriFieldTypeString",
          "alias": "CITY_NAME",
          "sqlType": "sqlTypeOther",
          "length": 40,
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "STATE_FIPS",
          "type": "esriFieldTypeString",
          "alias": "STATE_FIPS",
          "sqlType": "sqlTypeOther",
          "length": 2,
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "STATE_NAME",
          "type": "esriFieldTypeString",
          "alias": "STATE_NAME",
          "sqlType": "sqlTypeOther",
          "length": 25,
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "STATE_CITY",
          "type": "esriFieldTypeString",
          "alias": "STATE_CITY",
          "sqlType": "sqlTypeOther",
          "length": 7,
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "TYPE",
          "type": "esriFieldTypeString",
          "alias": "TYPE",
          "sqlType": "sqlTypeOther",
          "length": 25,
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "CAPITAL",
          "type": "esriFieldTypeString",
          "alias": "CAPITAL",
          "sqlType": "sqlTypeOther",
          "length": 1,
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "ELEVATION",
          "type": "esriFieldTypeSmallInteger",
          "alias": "ELEVATION",
          "sqlType": "sqlTypeOther",
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "POP1990",
          "type": "esriFieldTypeInteger",
          "alias": "POP1990",
          "sqlType": "sqlTypeOther",
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "HOUSEHOLDS",
          "type": "esriFieldTypeInteger",
          "alias": "HOUSEHOLDS",
          "sqlType": "sqlTypeOther",
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "MALES",
          "type": "esriFieldTypeInteger",
          "alias": "MALES",
          "sqlType": "sqlTypeOther",
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "FEMALES",
          "type": "esriFieldTypeInteger",
          "alias": "FEMALES",
          "sqlType": "sqlTypeOther",
          "domain": null,
          "defaultValue": null
        },
        {
          "name": "GLOBALID",
          "type": "esriFieldTypeGlobalID",
          "alias": "GLOBALID",
          "sqlType": "sqlTypeOther",
          "length": 38,
          "domain": null,
          "defaultValue": null
        }
      ],
      "features": [
        {
          "attributes": {
            "OBJECTID": 69,
            "CITY_FIPS": "66000",
            "CITY_NAME": "San Diego",
            "STATE_FIPS": "06",
            "STATE_NAME": "California",
            "STATE_CITY": "0666000",
            "TYPE": "city",
            "CAPITAL": "N",
            "ELEVATION": 42,
            "POP1990": 1110549,
            "HOUSEHOLDS": 406096,
            "MALES": 566464,
            "FEMALES": 544085,
            "GLOBALID": "e2c94f46-17d3-4459-9675-600ae69f4d1f"
          },
          "geometry": {
            "x": -117.13666926135465,
            "y": 32.814997725516207
          }
        }
      ]
    },
    {
      "id": 2,
      "features": []
    }
  ]
}

Example two

The response below demonstrates the response returned by query when returnIdsOnly is false , returnCountOnly is false , and geometryPrecision is 4 .

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
{
  "layers": [
    {
      "id": 1,
      "features": [
        {
          "geometry": {
            "x": -178.2448,
            "y": 50.0125
          },
          "attributes": {
            "objectid": 3745682,
            "datetime": 1272210710000,
            "depth": 31.100000000000001,
            "eqid": "2010vma5",
            "latitude": 50.012500000000003,
            "longitude": -178.2448,
            "magnitude": 4.7999999999999998,
            "numstations": 112,
            "region": "Andreanof Islands, Aleutian Islands, Alaska",
            "source": "us",
            "version": "Q"
          }
        },
        {
          "geometry": {
            "x": -72.8651,
            "y": -37.4866
          },
          "attributes": {
            "objectid": 3745685,
            "datetime": 1272210142999,
            "depth": 40.600000000000001,
            "eqid": "2010vma4",
            "latitude": -37.486600000000003,
            "longitude": -72.865099999999998,
            "magnitude": 4.9000000000000004,
            "numstations": 58,
            "region": "Bio-Bio, Chile",
            "source": "us",
            "version": "7"
          }
        }
      ]
    },
    {
      "id": 2,
      "features": []
    }
  ]
}

Example three

The response below demonstrates the response returned by query when returnCountOnly is true

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
{
  "layers": [
    {
      "id" : 1,
      "count": 2
    },
    {
      "id" : 2,
      "count":0
    }
  ]
}

Example four

The response demonstrates the response returned by query when returnIdsOnly is true .

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "layers": [
    {
      "id": 0,
      "objectIdFieldName": "OBJECTID",
      "objectIds": [5]
    },
    {
      "id": 1,
      "objectIdFieldName": "OBJECTID",
      "objectIds": [1]
    }
  ]
}

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