FRAMES | NO FRAMES Description | Parameters | Examples | Response
Query - Feature Service (Operation)
URL http://<featureservice-url>/query
Parent Resource Feature Service
Required Capability Query

Description

This operation is supported from 10.1 onwards.

The query operation is performed on a feature service resource. The result of this operation is either a feature set for each layer in the query or a count of features for each layer (if returnCountOnly is set to true) or or an array of feature ids for each layer in the query (if returnIdsOnly is set to true)..

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

In the feature set response, the layer features will include their geometries. The records for tables will not.

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

New in 10.1 SP1

Query - Feature Service operation supports spatialRel and time parameters.

Query - Feature Service operation supports a new JSON representation of layerDefs parameter with option to specify output fields.

Parameters

Parameter Details
f Description: The response format. The default response format is html.

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

Values: html | json (when returnIdsOnly=true or returnCountOnly=true)
layerDefs Description: Allows you to filter the features of individual layers in the query by specifying definition expressions for those layers. Definition expression for a layer that is published with the service will be always honored.

Simple Syntax:

Syntax: layerId1:layerDef1;layerId2:layerDef2
where layerId1, layerId2 are the layer ids returned by the feature service resource

Example: 0:POP2000 > 1000000;5:AREA > 100000

JSON Syntax 1:

You can also use a JSON representation for Layer Definitions.

Syntax:
{ "<layerId1>" : "<layerDef1>" , "<layerId2>" : "<layerDef2>" }
where layerId1, layerId2 are the layer ids returned by the feature service resource

Example:
{"0":"POP2000 > 1000000","5":"AREA > 100000"}

JSON Syntax 2:

//New at 10.1 SP1
You can use this JSON representation of layer definition to specify output fields.

Syntax:
[{ "layerId" : <layerId1>,"where": "<where clause>", "outfields": "<field1>,<field2>"},{"layerId" : <layerId2>,"where": "<where clause>", "outfields": "<field1>,<field2>"}]
where layerId1, layerId2 are the layer ids returned by the feature service resource

Example:
[{"layerId" : 0, "where" : "OBJECTID<100", "outFields" : "*"}, {"layerId" : 1, "where" : "OBJECTID<323", "outFields" : "OBJECTID,CREATOR"}]
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
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.
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.
gdbVersion Description: GeoDatabase version to query. This parameter applies only if hasVersionedData property of the service and isDataVersioned property of the layer(s) queried are true.
If this is not specified, query will apply to published map’s version.

Syntax: 
gdbVersion=<version>
Example: 
gdbVersion=SDE.DEFAULT
returnGeometry //This option was added at 10.1

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

Note that if the outFields parameter is set to the wildcard "*", it implicitly implies returnGeometry=true and setting returnGeometry to false has no effect.

Values: true | false
maxAllowableOffset //This option was added at 10.1

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

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.

Values: false | true
returnZ //This option was added at 10.1

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 //This option was added at 10.1

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.
geometryPrecision //This option was added at 10.1

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

Example Usage

Example 1: Query layer ids 0 and 1:

http://servicesbeta2.esri.com/arcgis/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=html

JSON Response Syntax (when returnCountOnly=false)

{
  "layers":[
{ "id" : <layerId1>,
   "hasZ" : <true|false>,
   "hasM" : <true|false>,
    "features" : [<feature1>, <feature2>]
},
{ "id" : <layerId2>,
   "hasZ" : <true|false>,
   "hasM" : <true|false>,
    "features" : [<feature1>, <feature2>]
}  
]
}

JSON Response Syntax (when returnCountOnly=true)

{
  "layers":[
{ "id" : <layerId1>,
    "count" : <count>
},
{ "id" : <layerId2>,
   "count" : <count> 
}  
]
}

JSON Response Syntax (when returnIdsOnly=true)

{
  "layers":[
{ "id" : <layerId1>,
  "objectIdFieldName": <objectIdFieldName>,
  "objectIds": [<objectId1>,<objectId2>,<objectId3>]

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

JSON Response Example (returnIdsOnly=false and returnCountOnly=false)

{
  "layers": [
  {
    "id" : 1,
    "features" : [
    {
      "geometry" : {
        "x" : -178.24479999999991,
        "y" : 50.012500000000045
      },
      "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.865099999999927,
        "y" : -37.486599999999953
      },
      "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" : [ ] 
} 
  ] 
}

JSON Response Example (returnIdsOnly=false, returnCountOnly=false and geometryPrecision=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" : [ ] 
} 
  ] 
}

JSON Response Example (when returnCountOnly=true)

{
  "layers": 
  [
  {"id" : 1,"count": 2},
  {"id" : 2,"count":0} 
 ] 
}

JSON Response Example (when returnIdsOnly=true)

{
 "layers": [
  {
   "id": 0,
   "objectIdFieldName": "OBJECTID",
   "objectIds": [5]
  },
  {
   "id": 1,
   "objectIdFieldName": "OBJECTID",
   "objectIds": [1]
  }
 ]
}