FRAMES | NO FRAMES Description | Parameters | Examples | Response
Query (Operation)
URL http://<dynamic-layer-url>/query
Parent Resource Dynamic Layer / Table
Required Capability Data

Description

This operation is supported from 10.1 onwards.

The query operation is performed on a dynamic layer / table resource. The result of this operation is a featureset. This featureset 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 featureset. For tables, the featureset does not include geometries.

When output format f is kmz the result would always contain a Z value irrespective of returnZ property value. If the feature geometry does not support Z then 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.

Note:

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

Parameters

Parameter Details
layer // Required parameter

Description: Use this parameter to define a "dynamic layer".

Note:
  • id and definitionExpression are optional.
  • If output format is kmz(f=kmz) and the layer source is a feature dynamic dataLayer based on a data table, then set drawingInfo.
  • layerTimeOptions is valid only on those dynamic mapLayers that support time. Use timeInfo property on the dynamic layer resource to determine if the layer supports temporal queries.
  • Use "gdbVersion" on dynamic map layer definition to specify an alternate geodatabase version.
Syntax: 
{
    "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: 
{
  "id": 101,
  "source":
    {
      "type": "dataLayer",
      "dataSource":
      {
        "type": "table",
        "workspaceId": "MAP",
        "dataSourceName": "MAP.user1.Taxlots"
      }
    },
  "definitionExpression": "LotSize > 5000"
}
f Description: The response format. The default response format is html.
Note: f=kmz would always return Z values.

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

Values: html | json | amf (when outStatistics is specified)

Values: html | json (when either returnIdsOnly=true or returnCountOnly=true is specified.)
text Description: 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 a short hand 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 Description: 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, for envelopes and points, you can specify the geometry with a simpler 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 Description: 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 Description: 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 Description: The spatial relationship to be applied on the input geometry while performing the query. The supported spatial relationships include intersects, contains, envelope intersects, within, etc. The default spatial relationship is intersects (esriSpatialRelIntersects).

Values: esriSpatialRelIntersects | esriSpatialRelContains | esriSpatialRelCrosses | esriSpatialRelEnvelopeIntersects | esriSpatialRelIndexIntersects | esriSpatialRelOverlaps | esriSpatialRelTouches | esriSpatialRelWithin | esriSpatialRelRelation
relationParam Description: 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 please refer to the documentation for the spatial relate function.
where Description: A where clause for the query filter. Any legal SQL where clause operating on the fields in the layer is allowed.

Example: where=POP2000 > 350000
objectIds Description: The object IDs of this layer / table to be queried.

Syntax: objectIds=<objectId1>, <objectId2>

Example: objectIds=37, 462
time Description: 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.
outFields Description: The list of fields to be included in the returned resultset. 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: outFields=AREANAME,ST,POP2000
Example (wildcard usage): outFields=*
returnGeometry Description: If true, the resultset includes the geometry associated with each result. The default is true.

Values: true | false
maxAllowableOffset Description: 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 then maxAllowableOffset is assumed to be in the unit of the spatial reference of the map.

Example: maxAllowableOffset=2
geometryPrecision Description: 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: geometryPrecision=3
outSR Description: 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 map.
returnIdsOnly Description: If true, the response only includes an array of object IDs. Otherwise the response is a feature set. The default is false.

Note that while there is a limit on the number of features included in the feature set response, there is no limit on 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.

Values: false | true
returnCountOnly Description: 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: false | true
orderByFields Description: One or more field names using which the features/records need to be ordered. Use ASC or DESC, for ascending or descending order respectively, following every field to control the ordering.

Note:
  • orderByFields is supported on only those dynamic layers / tables that indicate supportsAdvancedQueries is true.
  • orderByFields defaults to ASC (ascending order) if <ORDER> is unspecified.


Syntax: orderByFields=field1 <ORDER>, field2 <ORDER>, field3 <ORDER>
Example: orderByFields=STATE_NAME ASC, RACE DESC, GENDER
outStatistics Description: The definitions for one or more field-based statistic to be calculated.

Note:
  • outStatistics is supported on only those dynamic layers / tables that indicate suppportsStatistics is true.
  • If outStatisticFieldName is empty or missing, then map server would assign a field name to the returned statistic field. A valid field name can only contain alpha-numberic characters and an underscore.
  • When using outStatistics the only other parameters that will be used are groupByFieldsForStatistics, orderByFields, text, time, and where.
  • Specifying geometry, objectIds, or gdbVersion parameters would return an error.


Values: 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: 
[
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var>",
    "onStatisticField": "Field1", 
    "outStatisticFieldName": "Out_Field_Name1"
  },
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var>",
    "onStatisticField": "Field2",
    "outStatisticFieldName": "Out_Field_Name2"
  }  
]
Example: 
[
  {
    "statisticType": "sum",
    "onStatisticField": "GENDER",
    "outStatisticFieldName": "PopulationByGender"
  },
  {
    "statisticType": "avg",
    "onStatisticField": "INCOME",
    "outStatisticFieldName": "AverageIncome"
  }
]
groupByFieldsForStatistics Description: One or more field names using which the values need to be grouped for calculating the statistics.

Note: groupByFieldsForStatistics is valid only when outStatistics parameter is used.

Syntax: groupByFieldsForStatistics=field1, field2
Example: groupByFieldsForStatistics=STATE_NAME, GENDER
returnZ Description: 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.

Note this parameter only applies if returnGeometry is true.
returnM Description: 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.

Note this parameter only applies if returnGeometry is true.

Example Usage

Example 1: Query using the text parameter on a dynamic layer based on an existing layer:

http://servicesbeta2.esri.com/arcgis/rest/services/Census/MapServer/dynamicLayer/query?layer={"id":101,"definitionExpression":"\"sub_region\" like 'Pacific'","source":{"type":"mapLayer","mapLayerId":3}}&where=&text=California&objectIds=&time=&geometry=&geometryType=esriGeometryEnvelope&inSR=&spatialRel=esriSpatialRelIntersects&relationParam=&outFields=&returnGeometry=true&maxAllowableOffset=&outSR=&returnIdsOnly=false&returnCountOnly=false&orderByFields=&groupByFieldsForStatistics=&outStatistics=&returnZ=false&returnM=false&f=pjson

JSON Response Syntax (when returnIdsOnly=false and returnCountOnly=false)

{
"displayFieldName" : "<displayFieldName>",
//fieldAliases deprecated at 10
"fieldAliases" : {
  "<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>
]
}

JSON Response Syntax (when returnIdsOnly=true)

{
"objectIdFieldName" : "<objectIdFieldName>",
"objectIds" : [ <objectId1>, <objectId2> ]
}

JSON Response Syntax (when returnCountOnly=true)

{
"count" : <count>
}

JSON Response Syntax (when groupByFieldsForStatistics and outStatistics 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
}