Query (Map Service/Dynamic Layer)

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 returnZ 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 statisticType when using outStatistics for map services published from ArcGIS Pro that reference enterprise geodatabase data. Layers that support percentiles include the supportsPercentileStatistics property as true , found in the advancedQueryCapabilities 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. The supportedQueryFormats layer property will list 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:

    • historicMoment to query from a given moment in an archive-enabled layer.
  • Supports returning 'number of unique values', instead of a list of unique value, off a field when values for both returnCountOnly and returnDistinctValues are true.

New at 10.5

  • Supports datum transformation.
  • Supports passing in SQL expressions in outStatistics . Check supportsSqlExpression on resources to find out whether the layer or table allows SQL expressions.

New at 10.4

  • Supports GeoJSON as a response format.
  • Supports passing in expressions in orderByFields and groupByFieldsForStatistics . When useStandardizedQueries is true , you can pass in expressions that conform to StandardizedQueries specifications. Otherwise, any expressions that are supported by the underlying database can be passed in.

New at 10.3.1

  • The exceededTransferLimit property is now included in the JSON response when paging through a query result with the resultOffset and resultRecordCount parameters. When exceededTransferLimit is true , it indicates there are more query results and you can continue to page through the results. When exceededTransferLimit is 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 resultOffset and resultRecordCount parameters to page through a query result.
  • Note that when you pass in one of these two parameters and orderByFields 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 provide orderByFields or else the query will fail.
  • query now supports true curves in an input geometry parameter.
  • query now returns true curves in output geometries when the returnTrueCurves parameter is set to true.
  • 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 advertises useStandardizedQueries is true. Learn more about standardized queries.
  • outStatistics now supports the gdbVersion parameter.

New at 10.1 SP1

  • Support for a new parameter named returnDistinctValues that accepts a Boolean value was added. When true, the query result would contain distinct values based on the fields specified in the outFields parameter.
  • outStatistics now supports the geometry parameter.

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

Request parameters

ParameterDetails

layer

(Required)

Use this parameter to define a dynamic layer.

Syntax

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
{
  "id": <layerOrTableId>, // optional
  "source": <layer source>,
  "definitionExpression": "<definitionExpression>", // optional
  "drawingInfo": ( // optional
    "renderer": <renderer>,
    "transparency": <transparency>,
    "scaleSymbols": <true | false >,
    "showLabels": <true | false >,
    "labelingInfo": <labeling info>
  },
  "layerTimeOptions": { // optional
    "useTime": <true | false>,
    "timeDataCumulative": <true | false>,
    "timeOffset": <timeOffset>,
    "timeOffsetUnits": "<esriTimeUnitsCenturies | esriTimeUnitsDays | esriTimeUnitsDecades | esriTimeUnitsHours |
                        esriTimeUnitsMilliseconds | esriTimeUnitsMinutes | esriTimeUnitsMonths | esriTimeUnitsSeconds |
                        esriTimeUnitsWeeks | esriTimeUnitsYears |esriTimeUnitsUnknown>"
  }
}

Example

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
{
  "id": 101,
  "source": {
    "type": "dataLayer",
    "dataSource": {
      "type": "table",
      "workspaceId": "MAP",
      "dataSourceName": "MAP.user1.Taxlots"
    }
  },
  "definitionExpression": "LotSize > 5000"
}

text

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 where <displayField> like '%<text>%' . The text is case sensitive. This parameter is ignored if the where parameter is specified. Example: text=Los

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 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

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
//JSON structures
geometryType=<geometryType>&geometry={geometry}

//Envelope simple syntax
geometryType=esriGeometryEnvelope&geometry=<xmin>,<ymin>,<xmax>,<ymax>

//Point simple syntax
geometryType=esriGeometryPoint&geometry=<x>,<y>

Syntax:

Examples

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
//JSON structure
geometryType=esriGeometryEnvelope&geometry={xmin: -104, ymin: 35.6, xmax: -94.32, ymax: 41}

//Envelope simple syntax
geometryType=esriGeometryEnvelope&geometry=-104,35.6,-94.32,41

//Point simple syntax
geometryType=esriGeometryPoint&geometry=-104,35.6

geometryType

The type of geometry specified by the geometry parameter. The geometry type can be an envelope, point, line, or 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 as a spatial reference JSON object. If the inSR is not specified, the geometry is assumed to be in the spatial reference of the map.

spatialRel

The spatial relationship to be applied on 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

relationParam

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.

where

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, where = CHAR_LENGTH(cntry_name) > 18

Example

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

objectIds

The object IDs of this layer or table to be queried.

Syntax

Use dark colors for code blocksCopy
1
objectIds=<objectId1>, <objectId2>

Example

Use dark colors for code blocksCopy
1
objectIds=37, 462

time

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

Use dark colors for code blocksCopy
1
2
3
4
5
//Time instant
time=<timeInstant>

//Time extent
time=<startTime>, <endTime>

Examples

Use dark colors for code blocksCopy
1
2
3
4
5
//Time instant (1 Jan 2008 00:00:00: GMT)
time=1199145600000

//Time extent (1 Jan 2008 00:00:00 GTM to  Jan 2008 00:00:00 GMT)
time=1199145600000, 1230768000000

distance

The buffer distance for the input geometries. The distance unit is specified by units . For example, if the distance is 100, the query geometry is a point, units is set to esriSRUnit_Meter , and all points within 100 meters of the point are returned. This parameter only applies if supportsQueryWithDistance is true .

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

Use dark colors for code blocksCopy
1
distance=<distance>

Example

Use dark colors for code blocksCopy
1
distance=100

units

The unit for calculating the buffer distance. This parameter only applies if supportsQueryWithDistance is true .

Values: esriSRUnit_Meter | esriSRUnit_StatuteMile | esriSRUnit_Foot | esriSRUnit_Kilometer | esriSRUnit_NauticalMile | esriSRUnit_USNauticalMile

outFields

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 returnGeometry to true . You can also specify the wildcard * as the value of this parameter. In this case, the query results include all the field values.

Example

Use dark colors for code blocksCopy
1
2
3
4
outFields=AREANAME,ST,POP2000

//Wildcard usage
outFields=*

returnGeometry

If true , the result set includes the geometry associated with each result. 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

geometryPrecision

This option can be used to specify 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).

Example

Use dark colors for code blocksCopy
1
geometryPrecision=3

outSR

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 outSR is not specified, the geometry is returned in the spatial reference of the map.

When using outSR with pbf , the pbf format will use coordinate quantization for layer queries. When an output spatial reference is not provided for a query operation, the Map Service derives coordinate quantization parameters from the layer's spatial reference. If the precision in the layer's spatial references is inadequate for the client application's use, it should pass in a spatial reference with suitable precision as the output spatial reference. If the layer's source spatial reference has the desired precision and it is suitable for the client's use, the client can use the source layer's spatial reference as the output spatial reference.

returnIdsOnly

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

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 . This option supersedes the returnIdsOnly parameter.

Values: true | false

returnExtentOnly

This option was added at 10.3. If true , the response only includes the extent of the features that would be returned by the query. If returnCountOnly=true , the response will return both the count and the extent. The default is false . This parameter applies only if the supportsReturningQueryExtent property of the layer is true .

Values: true | false

orderByFields

This option was added at 10.1. One or more field names or expressions that the features/records need to be ordered by. Use ASC or DESC for ascending or descending order, respectively.

orderByFields is supported on only those layers/tables that indicate supportsAdvancedQueries is true . At 10.4, expressions are allowed in addition to field name. When StandardizedQueries is enabled, only expressions that conform to the specifications are allowed. When StandardizedQueries is disabled, you can pass in any expression that the underlying database allows.

Syntax

Use dark colors for code blocksCopy
1
orderByFields=expression1 <ORDER>, expression2 <ORDER>, expression3 <ORDER>

Examples

Use dark colors for code blocksCopy
1
2
3
orderByFields=STATE_NAME ASC, RACE DESC, GENDER

orderByFields=POPULATION / SHAPE_AREA

outStatistics

The definitions for one or more field-based statistics to be calculated. When using outStatistics , the only other parameters that will be used are groupByFieldsForStatistics , orderByFields , text , time , and where .

At 10.8.1, support for the percentile statisticType was added. For more information, see the percentile statistics type section below. At 10.5, expressions are allowed in addition to field name. When StandardizedQueries is enabled, only expressions that conform to the specifications are allowed. When StandardizedQueries is disabled, you can pass in any expression that the underlying database allows. At 10.2, support for the gdbVersion parameter was added. At 10.1 SP1, support for the geometry parameter was added.

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

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var | percentile_cont | percentile_desc>",
    "onStatisticField": "Field1",
    "statisticParameters": {   //only needed for percentile statistic type
      "value": value
    },
    "outStatisticFieldName": "Out_Field_Name1"
  },
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var | percentile_cont | percentile_desc>",
    "onStatisticField": "Field2",
    "statisticParameters": {   //only needed for percentile statistic type
      "value": value
    },
    "outStatisticFieldName": "Out_Field_Name2"
  }
]

Example One

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
[
  {
    "statisticType": "sum",
    "onStatisticField": "GENDER",
    "outStatisticFieldName": "PopulationByGender"
  },
  {
    "statisticType": "avg",
    "onStatisticField": "INCOME",
    "outStatisticFieldName": "AverageIncome"
  }
]

Example Two

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
[
  {
    "statisticType": "avg",
    "onStatisticField": "Production / AreaSqKm",
    "outStatisticFieldName": "AvgProdPerSqKM"
  }
]

groupByFieldsForStatistics

One or more field names using the values that need to be grouped for calculating statistics.

Syntax

Use dark colors for code blocksCopy
1
groupByFieldsForStatistics=expression1, expression2

Syntax:

Examples

Use dark colors for code blocksCopy
1
2
3
4
groupByFieldsForStatistics=STATE_NAME, GENDER

//Group by month when StandardizedQueries is enabled
groupByFieldsForStatistics=extract(month from incident_date)

returnZ

If true , z-values will be included in the results if the features have z-values. Otherwise, z-values are not returned. The default is false .

Values: true | false

returnM

If true , m-values will be included in the results if the features have m-values. Otherwise, m-values are not returned. The default is false .

Values: true | false

returnDistinctValues

This option was added at 10.1 SP1. If true , returns distinct values based on the fields specified in outFields . This parameter applies only if the supportAdvancedQueries property of the layer is true .

Values: true | false

returnTrueCurves

This option was added at 10.3. If true , returns true curves in output geometries; otherwise, curves get converted to densified polylines or polygons.

Values: true | false

resultOffset

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 query operation. This parameter applies only if the supportsPagination property of the layer is true . The default is 0.

Example

Use dark colors for code blocksCopy
1
resultOffset=50

resultRecordCount

This option was added at 10.3. This option can be used to specify the number of records in the response returned by the query operation. This parameter applies only if the supportsPagination property of the layer is true . When resultOffset is specified but this parameter is not, the map service defaults it to maxRecordCount .

Example

Use dark colors for code blocksCopy
1
resultRecordCount=10

datumTransformation

This option was added at 10.5 Use this parameter to apply a datum transformation while projecting geometries in the results when outSR is different than the layer's spatial reference.

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 transformation parameter in the Project operation.

Syntax

Use dark colors for code blocksCopy
1
2
3
4
datumTransformation=wkid1

datumTransformation={<dt1>}
datumTransformation={"wkt": "<wkt1>"}

Examples

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
//Apply a transformation
datumTransformation=1623

datumTransformations={"wkt": "GEOGTRAN[\"S_JTSK_To_WGS_1984_1\", GEOGCS[\"GCS_S_JTSK\", DATUM[\"D_S_JTSK\", SPHEROID[\"Bessel_1841\", 6377397.155, 299.1528128]], PRIMEM[\"Greenwich\", 0.0], UNIT[\"Degree\", 0.0174532925199433]], GEOGCS[\"GCS_WGS_1984\", DATUM[\"D_WGS_1984\", SPHEROID[\"WGS_1984\", 6378137.0, 298.257223563]], PRIMEM[\"Greenwich\", 0.0], UNIT[\"Degree\", 0.0174532925199433]], METHOD[\"Position_Vector\"], PARAMETER[\"X_Axis_Translation\", 570.8], PARAMETER[\"Y_Axis_Translation\", 85.7], PARAMETER[\"Z_Axis_Translation\", 462.8], PARAMETER[\"X_Axis_Rotation\", 4.998], PARAMETER[\"Y_Axis_Rotation\", 1.587], PARAMETER[\"Z_Axis_Rotation\", 5.261], PARAMETER[\"Scale_Difference\", 3.56], OPERATIONACCURACY[1.0]]"}


//Apply a composite transformation
datumTransformation={"geoTransforms":[{"wkid":108889,"transformForward":true},{"wkid":1622,"transformForward":false}]}

historicMoment

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 supportsQueryWithHistoricMoment property is set to true . This property 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

f

The response format. The default response format is html . Protocol buffer (pbf ) format is only supported when the supportedQueryFormat property on the layer includes pbf .

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

Values: html | json (when outStatistics is specified)

Values: html | json | geojson | pbf (when either returnIdsOnly=true or returnCountOnly=true is specified)

Percentile statistic type

The percentile statisticType is supported if the supportsPercentileStatistics layer property (in advancedQueryCapabilities ) 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 statisticTypes , PERCENTILE_DISC (discrete) and PERCENTILE_CONT (continuous). Discrete returns a data value from within that dataset while continuous is an interpolated value.

The orderBy 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 orderBy set as ascending (ASC ) is 9, while the percentile for value 0.9 with orderBy set as descending (DESC ) is 2. The default is ASC .

Syntax

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
[
  {
    "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

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
[
  {
    "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:

Use dark colors for code blocksCopy
1
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 returnIdsOnly=false and returnCountOnly=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
{
  "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 returnIdsOnly=true

Use dark colors for code blocksCopy
1
2
3
4
{
  "objectIdFieldName": "<objectIdFieldName>",
  "objectIds": [<objectId1>, <objectId2>]
}

When returnCountOnly=true

Use dark colors for code blocksCopy
1
2
3
{
  "count": <count>
}

When groupByFieldsForStatistics and outStatistics are specified

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
{
  "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
}

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