Query (Map Service\Dynamic Layer)

Description

This operation is supported from 10.1 onward.

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.

NoteNote:

  • All parameters related to geometry will be ignored when querying tables.
  • 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.
  • JSON response contains an optional property exceededTransferLimit. This property will be true only if the number of records exceeds the maximum number configured by the server administrator.
  • The domains member is not included in field information objects returned with the response.

New in 10.5

New at 10.4

New at 10.3.1

NoteNote:

When not using the resultOffset and resultRecordCount parameters, the exceededTransferLimit property may also be included in the query results. In this case, the property will be true only if the number of records exceeds the maximum number configured by the server administrator.

NoteNote:

In some cases when using the resultOffset and resultRecordCount parameters, the exceededTransferLimit property may be included in the query results even though the value specified in the resultRecordCount has not been exceeded. This is due to internal spatial index filtering of the query results. For this reason you should always rely on the exceededTransferLimit property to determine if you should page through results rather than relying on the number of results returned from each page. In some extreme cases zero results can be returned, but the exceededTransferLimit property will be returned. In these cases you should continue paging though your results until exceededTransferLimit is no longer returned.

New at 10.3

New at 10.2

New at 10.1 SP1

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

Request Parameters

Parameter

Details

layer

//Required parameter.

Description: Use this parameter to define a dynamic layer.

NoteNote:

  • id and definitionExpression are optional.
  • If the output format is kmz (f=kmz), and the layer source is a feature dynamic dataLayer based on a data table, set drawingInfo.
  • layerTimeOptions is valid only on those dynamic mapLayers that support time. Use the 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.

NoteNote:

f=kmz would always return z-values.

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

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

Values: html | json | geojson (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 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

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, and so on. 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, 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

When standardized queries are enabled, where = CHAR_LENGTH(cntry_name) > 18.

objectIds

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

NoteNote:

There might be a drop in performance if the layer or table data source resides in an enterprise geodatabase and more than 1,000 objectIds are specified.

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 (1Jan 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.

distance

Description: 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.

Syntax: distance=<distance>

Example: distance=100

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.

This parameter only applies if supportsQueryWithDistance is true.

units

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

Description: 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: outFields=AREANAME,ST,POP2000

Example (wildcard usage): outFields=*

returnGeometry

Description: If true, the result set includes the geometry associated with each result. The default is true.

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

NoteNote:

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

returnExtentOnly

This option was added at 10.3.

NoteNote:

At 10.3, this option is only available for hosted feature services. At 10.3.1, this option is available for hosted and nonhosted feature services.

Description: 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.

Description: 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.

NoteNote:

  • 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.
  • orderByFields is supported on only those layers/tables that indicate supportsAdvancedQueries is true.
  • orderByFields defaults to ASC (ascending order) if <ORDER> is unspecified.
  • When used with outStatistics, only field names specified in outStatisticFieldName or groupByFieldsForStatistics are allowed.

Syntax: orderByFields=expression1 <ORDER>, expression2 <ORDER>, expression3 <ORDER>

Example: orderByFields=STATE_NAME ASC, RACE DESC, GENDER

Example: orderByFields=POPULATION / SHAPE_AREA

outStatistics

Description: The definitions for one or more field-based statistics to be calculated.

NoteNote:

  • 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.
  • outStatistics is supported on only those dynamic layers/tables that indicate suppportsStatistics is true.
  • If outStatisticFieldName is empty or missing, the map server would assign a field name to the returned statistic field. A valid field name can only contain alphanumeric characters and an underscore.
  • When using outStatistics, the only other parameters that will be used are groupByFieldsForStatistics, orderByFields, text, time, and where.
  • At version 10.1, specifying geometry, objectIds, or gdbVersion parameters would return an error.
  • At version 10.1 SP1, support for the geometry parameter was added.
  • At version 10.2, support for the gdbVersion parameter was added.

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 | expression1", 
    "outStatisticFieldName": "Out_Field_Name1"
  },
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var>",
    "onStatisticField": "Field2 | expression2",
    "outStatisticFieldName": "Out_Field_Name2"
  }  
]

Example:

[
  {
    "statisticType": "sum",
    "onStatisticField": "GENDER",
    "outStatisticFieldName": "PopulationByGender"
  },
  {
    "statisticType": "avg",
    "onStatisticField": "INCOME",
    "outStatisticFieldName": "AverageIncome"
  }
]

Example:

[
  {
    "statisticType": "avg",
    "onStatisticField": "Production / AreaSqKm",
    "outStatisticFieldName": "AvgProdPerSqKM"
  }
]

groupByFieldsForStatistics

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

NoteNote:

  • 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.
  • groupByFieldsForStatistics is valid only when the outStatistics parameter is used.

Syntax: groupByFieldsForStatistics=expression1, expression2

Example: groupByFieldsForStatistics=STATE_NAME, GENDER

Example: groupByFieldsForStatistics=extract(month from incident_date) to group by month when StandardizedQueries is enabled

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.

NoteNote:

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.

NoteNote:

This parameter only applies if returnGeometry is true.

returnDistinctValues

//This option was added at 10.1 SP1.

Description: 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.

Syntax: returnDistinctValues=<true | false>

Example: returnDistinctValues=true

NoteNote:

This parameter cannot be used when returnGeometry is true.

returnTrueCurves

//This option was added at 10.3.

Description: If true, returns true curves in output geometries; otherwise, curves get converted to densified polylines or polygons.

Syntax: returnTrueCurves=<true | false>

Example: returnTrueCurves=true

resultOffset

//This option was added at 10.3.

Description: 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: resultOffset=50

resultRecordCount

//This option was added at 10.3.

Description: 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: resultRecordCount=10

datumTransformation

//This option was added at 10.5

Description: Use this parameter to apply a datum transformation while projecting geometries in the results when outSR is different than the layer's spatial reference.

Note: while specifying transformation, you need to think about which datum transformation best applicable to project the layer (not the map service) to the outSR. sourceSpatialReference property in the layer resource reports which spatial reference features are stored in the source dataset.

For a list of valid datum transformation ID values and well-known text strings, see Geographic transformations.

Syntax: datumTransformation=wkid1.

Examples: datumTransformation=1623 to apply a transformation.

Syntax: datumTransformation={<dt1>}.

Examples: datumTransformation={"geoTransforms":[{"wkid":108889,"transformForward":true},{"wkid":1622,"transformForward":false}]} to apply a composite transformation.

For more information on datum transformation, please see transformation parameter in Project operation.

Example Usage

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

http://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)

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

3/3/2017