- URL:
- https://<dynamic-layer-url>/query
- Methods:
GET
- Required Capability:
- Data
- Version Introduced:
- 10.1
Description
This operation is supported at 10.1 and later.
The query operation is performed on a dynamic layer/table resource. The result of this operation is a feature set. This feature set contains feature objects including the values for the fields requested by the user. For layers, if you request geometry information, the geometry of each feature is also returned in the feature set. For tables, the feature set does not include geometries.
Note that a WHERE clause (where
) or text field (text
) is required for a query.
When output format f
is kmz, the result would always contain a z-value irrespective of the return
property value. If the feature geometry does not support z, a default value of 0 would be returned for z.
For time-aware layers, users can use the time
parameter to specify the time instant or the time extent to query.
New at 10.8.1
The layer query operation supports percentile
as a statistic
when using out
for map services published from ArcGIS Pro that reference enterprise geodatabase data. Layers that support percentiles include the supports
property as true
, found in the advanced
layer object.
New at 10.7.1
- Map Services now support the protocol buffer (
pbf
) format. This format is supported on map services from ArcGIS Pro. Thesupported
layer property will listQuery Formats pbf
if it is available on the layer.
New at 10.7
- Support for
amf
output format was removed.
New at 10.6.1
-
Supports the following new parameter:
historic
to query from a given moment in an archive-enabled layer.Moment
-
Supports returning 'number of unique values', instead of a list of unique value, off a field when values for both
return
andCount Only return
are true.Distinct Values
New at 10.5
- Supports datum transformation.
- Supports passing in SQL expressions in
out
. CheckStatistics supports
on resources to find out whether the layer or table allows SQL expressions.Sql Expression
New at 10.4
- Supports GeoJSON as a response format.
- Supports passing in expressions in
order
andBy Fields group
. WhenBy Fields For Statistics use
isStandardized Queries true
, you can pass in expressions that conform toStandardized
specifications. Otherwise, any expressions that are supported by the underlying database can be passed in.Queries
New at 10.3.1
- The
exceeded
property is now included in the JSON response when paging through a query result with theTransfer Limit result
andOffset result
parameters. WhenRecord Count exceeded
isTransfer Limit true
, it indicates there are more query results and you can continue to page through the results. Whenexceeded
isTransfer Limit false
, it indicates that you have reached the end of the query results.
New at 10.3
- Supports pagination in a query layer. Use the
result
andOffset result
parameters to page through a query result.Record Count - Note that when you pass in one of these two parameters and
order
is left empty, map service uses the object-id field to sort the result. For a query layer with a pseudocolumn as the object-id field (for example, FID), you must provideBy Fields order
or else the query will fail.By Fields query
now supports true curves in an inputgeometry
parameter.query
now returns true curves in output geometries when thereturn
parameter is set to true.True Curves - Learn more about JSON Curve Objects in Geometry Objects.
New at 10.2
- The
where
parameter value must conform to the standardized queries, if the dynamic layer/table resource advertisesuse
is true. Learn more about standardized queries.Standardized Queries out
now supports theStatistics gdb
parameter.Version
New at 10.1 SP1
- Support for a new parameter named
return
that accepts a Boolean value was added. When true, the query result would contain distinct values based on the fields specified in theDistinct Values out
parameter.Fields out
now supports theStatistics geometry
parameter.
You can provide arguments to the query operation as query parameters defined in the parameters table below.
Request parameters
Parameter | Details |
---|---|
(Required) | Use this parameter to define a dynamic layer. Syntax
Example
|
| A literal search text. If the layer has a display field associated with it, the server searches for this text in this field. This parameter is shorthand for a WHERE clause of |
| 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 ArcGIS REST API. In addition to the JSON structures, for envelopes and points, you can specify the geometry with a simpler comma-separated syntax. Syntax
Syntax: Examples
|
| The type of geometry specified by the Values: |
| The spatial reference of the input |
| The spatial relationship to be applied on the input Values: |
| The spatial relate function that can be applied while performing the query operation. An example for this spatial relate function is FFFTTT***. For more information on this spatial relate function, refer to the documentation for the spatial relate function. |
| A WHERE clause for the query filter. Any legal SQL WHERE clause operating on the fields in the layer is allowed. When standardized queries are enabled, Example
|
| The object IDs of this layer or table to be queried. Syntax
Example
|
| The time instant or the time extent to query. A null value specified for start time or end time will represent infinity for start or end time, respectively. Syntax
Examples
|
| The buffer distance for the input geometries. The distance unit is specified by The geodesic buffer is created based on the datum of the output spatial reference if it exists. If there is no output spatial reference, the input geometry spatial reference is used. Otherwise, the native layer spatial reference is used to generate the geometry buffer used in the query. Syntax
Example
|
| The unit for calculating the buffer distance. This parameter only applies if Values: |
| The list of fields to be included in the returned result set. This list is a comma-delimited list of field names. If you specify the shape field in the list of return fields, it is ignored. To request geometry, set Example
|
| If Values: |
| This option can be used to specify the Example
|
| This option can be used to specify the number of decimal places in the response geometries returned by the Example
|
| The spatial reference of the returned geometry. The spatial reference can be specified as a well-known ID or as a spatial reference JSON object. If When using |
| If Values: |
| If Values: |
| This option was added at 10.3. If Values: |
| This option was added at 10.1. One or more field names or expressions that the features/records need to be ordered by. Use
Syntax
Examples
|
| The definitions for one or more field-based statistics to be calculated. When using At 10.8.1, support for the Syntax: An array of statistic definitions. A statistic definition specifies the type of statistic, the field on which it is to be calculated, and the resulting output field name. Syntax example
Example One
Example Two
|
| One or more field names using the values that need to be grouped for calculating statistics. Syntax
Syntax: Examples
|
| If Values: |
| If Values: |
| This option was added at 10.1 SP1. If Values: |
| This option was added at 10.3. If Values: |
| This option was added at 10.3. This option can be used to specify the number of records to skip in the response returned by the Example
|
| This option was added at 10.3. This option can be used to specify the number of records in the response returned by the Example
|
| This option was added at 10.5 Use this parameter to apply a datum transformation while projecting geometries in the results when For a list of valid datum transformation ID (WKID) values and well-known text (WKT) strings, see Using spatial references. For more information on datum transformation, see the Syntax
Examples
|
| This option was added at 10.6.1. The historic moment to query. This parameter applies only if the layer is archiving enabled and the Syntax
Example
|
| The response format. The default response format is Values: Values: Values: |
Percentile statistic type
The percentile statistic
is supported if the supports
layer property (in advanced
) is true
. The percentile indicates the value below or above which a given percentage of values in a group of data values falls. For example, the ninetieth percentile (value 0.9) is the value below which 90 percent of the data values may be found. For percentile statistics, there are two statistic
, PERCENTILE
(discrete) and PERCENTILE
(continuous). Discrete returns a data value from within that dataset while continuous is an interpolated value.
The order
statistic parameter can also be used to calculate the percentile. For example, in a set of 10 values from 1 to 10, the percentile value
for 0.9 with order
set as ascending (ASC
) is 9, while the percentile for value
0.9 with order
set as descending (DESC
) is 2. The default is ASC
.
Syntax
[
{
"statisticType": "<PERCENTILE_CONT | PERCENTILE_DISC>",
"statisticParameters": {
"value": percentile_value,
"orderBy": "<ASC | DESC>"
},
"onStatisticField": "Field1",
"outStatisticFieldName": "Out_Field_Name1"
},
{
"statisticType": "<PERCENTILE_CONT | PERCENTILE_DISC>",
"statisticParameters": {
"value": percentile_value,
"orderBy": "<ASC | DESC>"
},
"onStatisticField": "Field2",
"outStatisticFieldName": "Out_Field_Name2"
}
]
Example
[
{
"statisticType": "PERCENTILE_CONT",
"statisticParameters": {
"value": 0.9
},
"onStatisticField": "NEAR_DIST",
"outStatisticFieldName": "pop90_cont"
},
{
"statisticType": "PERCENTILE_DISC",
"statisticParameters": {
"value": 0.9,
"orderBy": "DESC"
},
"onStatisticField": "population",
"outStatisticFieldName": "pop90_desc"
}
]
Example usage
Query using the text parameter on a dynamic layer based on an existing layer:
https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/dynamicLayer/query?layer={"id":101,"definitionExpression":"\"sub_region\" like 'Pacific'","source":{"type":"mapLayer","mapLayerId":3}}&text=California&returnGeometry=true&f=html
JSON Response syntax
When return
and return
{
"displayFieldName": "<displayFieldName>",
"fieldAliases": { //fieldAliases deprecated at 10
"<fieldName1>": "<fieldAlias1>",
"<fieldName2>": "<fieldAlias2>"
},
"fields": [
{
"name": "<fieldName1>",
"type": "<fieldType1>",
"alias": "<fieldAlias1>",
"length": "<length1>"
},
{
"name": "<fieldName2>",
"type": "<fieldType2>",
"alias": "<fieldAlias2>",
"length": "<length2>"
}
],
"geometryType": "<geometryType>", //for layers only
"spatialReference": <spatialReference>, //for layers only
"hasZ": <true|false>, //added in 10.1
"hasM": <true|false>, //added in 10.1
"features": [ //features may include geometry for layers only
<feature1>, <feature2>
]
}
When return
{
"objectIdFieldName": "<objectIdFieldName>",
"objectIds": [<objectId1>, <objectId2>]
}
When return
{
"count": <count>
}
When group
and out
are specified
{
"displayFieldName": "",
"fieldAliases": {
"alias1": "fieldAlias1",
"alias2": "fieldAlias2"
},
"fields": [
{
"name": "fieldName1",
"type": "fieldType1",
"alias": "fieldAlias1",
"length": fieldLength1
},
{
"name": "fieldName2",
"type": "fieldType2",
"alias": "fieldAlias2",
"length": fieldLength2
}
],
"features": [<feature1>, <feature2>] //Feature object without geometry
}