- URL:https://<featureservice-url>/query
- 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.
Nota:
If the query results include an empty feature set, the field set is not returned.
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.
Nota:
Date field values in a query response from a Google BigQuery feature service are assumed to be in UTC. Values from database fields of the timestamp type are accurate as they are returned from the database in UTC. Values from database fields of the time, date, and datetime type may not be accurate as they may not be returned from the database in UTC. To avoid potential issues, feature services can be published from ArcGIS Pro that exclude the non-UTC time, date, and datetime fields.
New at 10.9
A new parameter, timeReferenceUnknownClient, has been added at 10.9. Setting timeReferenceUnknownClient as trueindicates 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
| Parameter | Details |
|---|---|
| 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 Example |
| 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 API REST de ArcGIS. In addition to the JSON structures, you can specify the geometry of envelopes and points with a simple comma-separated syntax. Syntax:
Examples:
|
| 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 |
| 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 Example |
| 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 |
| 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). |
| 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. Nota:If returnGeometry is false, specifying the multipatchOption is not required. 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. Nota:The SQL format native is supported only when useStandardizedQuery=false. Values: none | standard | native |
| timeReferenceUnknownClient | Setting timeReferenceUnknownClient as trueindicates 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. Nota:ArcGIS Pro 2.7 or newer can work with these feature services. 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:
<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 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.
With editor tracking date fields, use the editFieldsInfo array's dateFieldsTimeReference property when available to identify the time zone. When this is not available, use the dateFieldsTimeReference property of the feature service layer. If the feature service layers dateFieldsTimeReference property is null, then the editor tracking date values are in UTC. To find the time zone of the time aware layer, locate the timeZone property in the timeInfo array within the layer json.
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
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
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.
Nota:
Not all clients support working with services that have an Unknown time zone.SQL Format
The table summarizes the sqlFormat 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=htmlJSON Response syntax examples
Example one
The syntax example below demonstrates the structure of the response returned by query when returnCountOnly 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 returnCountOnly 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 returnIdsOnly 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 returnIdsOnly is false and returnCountOnly 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 returnIdsOnly is false, returnCountOnly is false, and geometryPrecision 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 returnCountOnly is true
{
"layers": [
{
"id" : 1,
"count": 2
},
{
"id" : 2,
"count":0
}
]
}Example four
The response demonstrates the response returned by query when returnIdsOnly is true.
{
"layers": [
{
"id": 0,
"objectIdFieldName": "OBJECTID",
"objectIds": [5]
},
{
"id": 1,
"objectIdFieldName": "OBJECTID",
"objectIds": [1]
}
]
}