Description

Note: Prior to 10, the query operation could only be performed on layers. From 10 onward, in addition to layers, the query operation can be performed on tables as well.

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.

Note that all parameters related to geometry will be ignored when querying tables.

New in 10.1 SP1

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

New in 10.1

• Support for orderByFields, outStatistics, and groupByFieldsForStatistics was added for both layers / tables.
• Support for returnZ and returnM was added for layers. Default value for returnZ and returnM is false.
• 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.
• Support for gdbVersion parameter was added. Use this parameter to specify the geodatabase version to query.
• geometryPrecision parameter was introduced. This option can be used to specify the number of decimal places in the response geometries returned by the query operation.
• 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.

New in 10.0 SP1

• At 10.0 SP1, support for returning the count (number of features/records) that would be returned by a query, was added for both layers / tables.

New in 10.0

• Support for querying layers / tables based on time was added at 10. For time-aware layers, users can use the time parameter to specify the time instant or the time extent to query.
• A new returnIdsOnly parameter was introduced. If set to false (default), the response will be a featureset. If true, the response will be an array of object IDs.
• 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.
• Support for query based on objectIds was added.
• Support for f=amf was added.
• Support for generalizing geometries returned by the query operation was added.
• query operation returns additional fields array (JSON and AMF only) that contains array of field information for returned values.  This array contains only fields specified in outFields parameter. See Layer/Table for defails on fields. NOTE: domains member is not included in field information objects returned with the response.
• fieldAliases member is deprecated.

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

Parameters

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

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

Example Usage

Example 1: Query using the text parameter on the states layer of the ESRI_StateCityHighway_USA on sampleserver1:

Example 2: Query using a where statement on the same layer. The output is JSON format:

Example 3: Query strings are case sensitive. In this example, UPPER is used to make the query case insensitive:

Example 4: Querying the same states layer using geometry (envelope):

Example 5: Querying the states layer by both geometry (envelope) and a where statement:

Example 6: Querying the states layer by where statement, specifying a list of fields to return, and requesting no geometry in the results:

Example 7: Querying the states layer by text parameter and requesting the geometry with the well-known ID of 102113 (Web Mercator):

Example 8: Query a table using a WHERE clause and return OBJECTIDs only http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/SanFrancisco/311Incidents/MapServer/1/query?objectIds=&where=agree_with_incident+%3D+1&returnGeometry=true&returnIdsOnly=true&f=html

Example 9: Using groupByFieldsForStatistics and outStatistics:
http://servicesbeta2.esri.com/arcgis/rest/services/Census/MapServer/3/query?where=&text=&objectIds=&time=&geometry=&geometryType=esriGeometryEnvelope&inSR=&spatialRel=esriSpatialRelIntersects&relationParam=&outFields=&returnGeometry=true&maxAllowableOffset=&outSR=&returnIdsOnly=false&returnCountOnly=false&orderByFields=&groupByFieldsForStatistics=sub_region&outStatistics=[{"statisticType":"sum","onStatisticField":"pop2007","outStatisticFieldName":"Population_2007"},{"statisticType":"avg","onStatisticField":"AVE_FAM_SZ","outStatisticFieldName":"Average_Family_Size"}]&returnZ=false&returnM=false&gdbVersion=&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
}

JSON Response Example when returnIdsOnly=false and returnCountOnly=false

{
"displayFieldName" : "AREANAME",

"fieldAliases" : {
    "ST" : "ST",
    "POP2000" : "Population - 2000",
    "AREANAME" : "City Name"

},

"fields" : [
{
    "name" : "ST",
    "alias" : "ST",
    "type" : "esriFieldTypeString",
    "length" : 2
},
{

    "name" : "POP2000",
    "alias" : "Population - 2000",
        "type" : "esriFieldTypeInteger"
},

{
    "name" : "AREANAME",
    "alias" : "City Name",
    "type" : "esriFieldTypeString",
    "length" : 255
}
],

"geometryType" : "esriGeometryPoint",
"spatialReference" : {"wkid" : 4326},
"features" : [
    {
    "attributes" : {
        "ST" : "CA",
        "POP2000" : 3694820,
        "AREANAME" : "Los Angeles"
    },
    "geometry" : { "x" : -118.37, "y" : 34.086 }
    },
    {
    "attributes" : {
        "ST" : "CA",
        "POP2000" : 461522,
        "AREANAME" : "Long Beach"
    },
    "geometry" : { "x" : -118.15, "y" : 33.80 }
    }
]
}

JSON Response Example when returnIdsOnly=true

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

JSON Response Example when returnCountOnly=true

{
"count":48
}

JSON response example when groupByFieldsForStatistics and outStatistics are specified

{
 "displayFieldName": "",
 "fieldAliases": {
  "sub_region": "SUB_REGION",
  "Population_2007": "Population_2007",
  "Average_Family_Size": "Average_Family_Size"
 },
 "fields": [
  {
   "name": "sub_region",
   "type": "esriFieldTypeString",
   "alias": "SUB_REGION",
   "length": 20
  },
  {
   "name": "Population_2007",
   "type": "esriFieldTypeDouble",
   "alias": "Population_2007"
  },
  {
   "name": "Average_Family_Size",
   "type": "esriFieldTypeDouble",
   "alias": "Average_Family_Size"
  }
 ],
 "features": [
  {
   "attributes": {
    "sub_region": "Pacific",
    "Population_2007": 49731702,
    "Average_Family_Size": 3.2439999999999998
   }
  },
  {
   "attributes": {
    "sub_region": "Mountain",
    "Population_2007": 21492235,
    "Average_Family_Size": 3.165
   }
  },
  {
   "attributes": {
    "sub_region": "New England",
    "Population_2007": 14515009,
    "Average_Family_Size": 3.0249999999999999
   }
  },
  {
   "attributes": {
    "sub_region": "West North Central",
    "Population_2007": 20384497,
    "Average_Family_Size": 3.044285714285714
   }
  },
  {
   "attributes": {
    "sub_region": "East North Central",
    "Population_2007": 47176974,
    "Average_Family_Size": 3.0940000000000003
   }
  },
  {
   "attributes": {
    "sub_region": "Middle Atlantic",
    "Population_2007": 41116339,
    "Average_Family_Size": 3.1566666666666663
   }
  },
  {
   "attributes": {
    "sub_region": "South Atlantic",
    "Population_2007": 58943344,
    "Average_Family_Size": 3.0333333333333332
   }
  },
  {
   "attributes": {
    "sub_region": "East South Central",
    "Population_2007": 18077309,
    "Average_Family_Size": 3.0275000000000003
   }
  },
  {
   "attributes": {
    "sub_region": "West South Central",
    "Population_2007": 34910821,
    "Average_Family_Size": 3.1124999999999998
   }
  }
 ]
}