- 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 return
is set to true
), or an array of feature IDs for each layer in the query (if return
is set to true
).
While there is a limit to the number of features included in the response (see the max
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 return
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, time
, has been added at 10.9. Setting time
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 strip
, embed
, and externalize
.
New at 10.5
The feature service layer Query operation supports the return
, historic
, and sql
parameters.
New at 10.1 SP1
The Feature Service Query operation supports spatial
and time
parameters. The Feature Service Query operation supports a new JSON representation of the layer
parameter with an option to specify output fields.
Request parameters
Parameter | Details |
---|---|
| 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
Example
|
|
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:
Examples:
|
|
The type of geometry specified by the Values: |
|
The spatial reference of the input The spatial reference can be specified as either a well-known ID or a spatial reference JSON object. If |
|
The spatial relationship to be applied to the input Values: |
|
The time instant or the time extent to query. Time instant Syntax: Example: Time extent Syntax: Example: A null value specified for start time or end time will represent infinity for start or end time, respectively. Example: |
| 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 |
| The geodatabase version to query. This parameter applies only if the If Syntax: Example: |
| 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 Syntax
Example
|
| If Values: |
| This option can be used to specify the Example
|
| If 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 Values: |
| If Values: |
| If Values: |
| If Values: |
| The number of decimal places in the response geometries returned by the
|
| How the geometry of a multipatch feature will be returned. This parameter only applies if the layers in the service have the Values: |
(Optional) | This option was added at 10.5. When set to Values: |
| The Values: |
| Setting 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 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 Value: |
| The response format. The default response format is Values: Values: |
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:
<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
where=POP2000 > 350000
where=CITY_NAME = 'Barrington'
Date-Time Queries
In general, the date
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 date
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
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 date
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
in UTC:
Querying records in three different time zones
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 date
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 date
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 sql
parameter and what you can expect from the query API.
sqlFormat value | useStandardizedQuery=true | useStandardizedQuery=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:
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 return
is false
:
{
"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 return
is true
.
{
"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 return
is true
.
{
"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 return
is false
and return
is false
.
{
"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 return
is false
, return
is false
, and geometry
is 4
.
{
"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 return
is true
{
"layers": [
{
"id" : 1,
"count": 2
},
{
"id" : 2,
"count":0
}
]
}
Example four
The response demonstrates the response returned by query
when return
is true
.
{
"layers": [
{
"id": 0,
"objectIdFieldName": "OBJECTID",
"objectIds": [5]
},
{
"id": 1,
"objectIdFieldName": "OBJECTID",
"objectIds": [1]
}
]
}