FRAMES | NO FRAMES Description | Parameters | Examples | Response
Query (Operation)
URL http://<featurelayer-url>/query
Parent Resource Layer

Description

The query operation is performed on a feature service layer resource. The result of this operation is either a feature set or an array of feature ids (if returnIdsOnly is set to true).

Either a spatial or attribute query must be defined at a minimum to return results. This means either the geometry parameter (and associated parameters like spatial relationship) or the where clause parameter must be defined at a minimum.

The maximum number of records returned in a single query is defined when the feature service is published. It cannot be changed by the consumer of the service.  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. 

In the feature set response, the layer features will include their geometries. The records for tables will not since no spatial column is present. 

You can provide arguments to the query operation as query parameters defined in the parameters table below.  Note, if the table is not spatially enabled (does not have a spatial column) you can only define the where clause (where), output fields (outFields), and result format (f).

Parameters

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

Values: html | json | pjson
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 REST API. In addition to the JSON structures, for envelopes and points, you can specify the geometry using simple comma-separated syntax. If not defined, a where clause must be defined to return results.

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, polygon, or multipoint. The default geometry type is an envelope.

Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope
inSR Description: The well-known ID of the spatial reference of the input geometry. If the inSR is not specified, the geometry is assumed to be in the spatial reference of the layer/table (defined by the geometry column).
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
objectIds Description: The object IDs of the layer/table to be queried.

Syntax: objectIds=<objectId1>, <objectId2>

Example: objectIds=37, 462
orderByFields Description: One or more field names using which the features/records need to be ordered. Use ASC or DESC, for ascending or descending respectively, following every field to control the ordering.

Note:
orderByFields is supported on only those 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
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 geometry 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. Note, you must still set returnGeometry to true to return geometry. 

Example: outFields=AREANAME,ST,POP2000
Example (wildcard usage): outFields=*
outSR Description: The well-known ID of the spatial reference for the returned geometry. If outSR is not specified, the geometry is returned in the spatial reference of the table (defined by the geometry column).
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
returnGeometry Description: If true, the resultset includes the geometry associated with each result. The default is true.

Note that even if the outFields parameter is set to the wildcard "*", returnGeometry must be set to true to return geometry.

Values: true | false
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.

Note that when objectIds are specified, setting this parameter to true is invalid.

Values: false | true
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 | esriSpatialRelOverlaps | esriSpatialRelTouches | esriSpatialRelWithin
where Description: A where clause for the query filter. Any legal SQL where clause operating on the fields in the layer/table is allowed. Leave the where clause empty to return all rows when the geometry parameter is defined. If the geometry parameter is not defined, use "1=1" to return all rows.

Example: where=POP2000 > 350000

Example Usage

Example 1: Query using the where parameter on the first layer in the "USA" feature service:

http://sampleserver10.arcgisonline.com/arcgis/rest/services/USA/FeatureServer/0/query?where=NAME like '%Los%'

Example 2: Query using a envelope and a where clause to filter the results returned from the first layer in the "USA" feature services. A restricted set of fields are defined. In addition, geometry is returned in the output spatial reference id 102100 (Web Mercator). The output is in JSON format:

http://sampleserver10.arcgisonline.com/arcgis/rest/services/USA/FeatureServer/0/query?geometry=-110,32,-100,45&geometryType=esriGeometryEnvelope& inSR=&spatialRel=esriSpatialRelIntersects&where=ST='WY'&returnGeometry=true&outSR=102100&outFields=NAME,POP2000,FID&f=json

JSON Response Syntax (when returnIdsOnly=false)

{
  "objectIdFieldName": "<objectIdFieldName>",
  "globalIdFieldName": "<globalIdFieldName>",
  "geometryType": "<geometryType>",
  "spatialReference": <spatialReference>,
  "fields": [
    {
      "name": "<fieldName1>",
      "type": "<fieldType1>",
      "alias": "<fieldAlias1>",
      "length": "<length1>"
    },
    {
      "name": "<fieldName2>",
      "type": "<fieldType2>",
      "alias": "<fieldAlias2>",
      "length": "<length2>"
    }
  ],
  "features": [
    <feature1>,
    <feature2>
  ]
}

JSON Response Syntax (when returnIdsOnly=true)

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

JSON Response Example (when returnIdsOnly=false)

{
  "objectIdFieldName" : "FID", 
  "globalIdFieldName" : "", 
  "geometryType" : "esriGeometryPoint", 
  "spatialReference" : {
    "wkid" : 4326
  }, 
  "fields" : [
    {
      "name" : "FID", 
      "type" : "esriFieldTypeInteger", 
      "alias" : "FID", 
      "sqlType" : "sqlTypeInteger", 
      "domain" : null
    }, 
    {
      "name" : "NAME", 
      "type" : "esriFieldTypeString", 
      "alias" : "NAME", 
      "sqlType" : "sqlTypeNVarchar", "length" : 40, 
      "domain" : null
    }, 
    {
      "name" : "COUNTRY", 
      "type" : "esriFieldTypeString", 
      "alias" : "COUNTRY", 
      "sqlType" : "sqlTypeNVarchar", "length" : 12, 
      "domain" : null
    }, 
    {
      "name" : "POPULATION", 
      "type" : "esriFieldTypeDouble", 
      "alias" : "POPULATION", 
      "sqlType" : "sqlTypeFloat", 
      "domain" : null
    }, 
    {
      "name" : "CAPITAL", 
      "type" : "esriFieldTypeString", 
      "alias" : "CAPITAL", 
      "sqlType" : "sqlTypeNVarchar", "length" : 1, 
      "domain" : null
    }
  ], 
  "features" : [
    {
      "attributes" : {
        "FID" : 1, 
        "NAME" : "Murmansk", 
        "COUNTRY" : "Russia", 
        "POPULATION" : 468000, 
        "CAPITAL" : "N"
      }, 
      "geometry" : 
      {
        "x" : 33.0860404968262, 
        "y" : 68.9635467529297
      }
    }, 
    {
      "attributes" : {
        "FID" : 2, 
        "NAME" : "Arkhangelsk", 
        "COUNTRY" : "Russia", 
        "POPULATION" : 416000, 
        "CAPITAL" : "N"
      }, 
      "geometry" : 
      {
        "x" : 40.6461601257324, 
        "y" : 64.5206680297852
      }
    }
  ]
} 

JSON Response Example (when returnIdsOnly=true)

{
  "objectIdFieldName" : "FID", 
  "objectIds" : [1, 2, 3, 4, 5, 7]
}