Query (Feature Service)
- URL:http://<featureservice-url>/query
- Required Capability:Query
- Version Introduced:10.1
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 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 (see the maxRecordCount property of the feature service), 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
Feature Service query operation supports spatialRel and time parameters.
Feature Service query operation supports a new JSON representation of layerDefs parameter with option to specify output fields.
Request 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:
Examples:
|
| 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 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 the hasVersionedData property of the service and the isDataVersioned property of the layer(s) queried are true. If gdbVersion is not specified, the query will apply to the 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. If the outFields parameter is set to the wildcard "*", it implicitly implies that 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. 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: true | false |
| 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: true | false |
| 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. This parameter only applies if returnGeometry is true and at least one of the layers hasZ property 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. This parameter only applies if returnGeometry is true and at least one of the layers hasM property 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://services.myserver.com/ERmEceOGq5cHrItq/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>,
"objectIdFieldName" : <fieldName>,
"globalIdFieldName" : <fieldName>,
"geometryType" : "<geometryType>", //for layers only
"spatialReference" : <spatialReference>, //for layers only
"hasZ" : <true|false>,
"hasM" : <true|false>,
"fields" : [
{"name" : "<fieldName1>", "type" : "<fieldType1>", "alias" : "<fieldAlias1>", "length" : "<length1>"},
{"name" : "<fieldName2>", "type" : "<fieldType2>", "alias" : "<fieldAlias2>", "length" : "<length2>"}],
"features" : [<feature1>, <feature2>]
},
{
"id" : <layerId2>,
"objectIdFieldName" : <fieldName>,
"globalIdFieldName" : <fieldName>,
"geometryType" : "<geometryType>", //for layers only
"spatialReference" : <spatialReference>, //for layers only
"hasZ" : <true|false>,
"hasM" : <true|false>,
"fields" : [
{"name" : "<fieldName1>", "type" : "<fieldType1>", "alias" : "<fieldAlias1>", "length" : "<length1>"},
{"name" : "<fieldName2>", "type" : "<fieldType2>", "alias" : "<fieldAlias2>", "length" : "<length2>"}],
"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" : 0,
"objectIdFieldName" : "OBJECTID",
"globalIdFieldName" : "",
"geometryType" : "esriGeometryPoint",
"spatialReference" : {
"wkid" : 4326,
"latestWkid" : 4326
},
"fields" : [
{
"name" : "OBJECTID",
"type" : "esriFieldTypeOID",
"alias" : "OBJECTID",
"sqlType" : "sqlTypeOther",
"domain" : null,
"defaultValue" : null
},
{
"name" : "CITY_FIPS",
"type" : "esriFieldTypeString",
"alias" : "CITY_FIPS",
"sqlType" : "sqlTypeOther", "length" : 5,
"domain" : null,
"defaultValue" : null
},
{
"name" : "CITY_NAME",
"type" : "esriFieldTypeString",
"alias" : "CITY_NAME",
"sqlType" : "sqlTypeOther", "length" : 40,
"domain" : null,
"defaultValue" : null
},
{
"name" : "STATE_FIPS",
"type" : "esriFieldTypeString",
"alias" : "STATE_FIPS",
"sqlType" : "sqlTypeOther", "length" : 2,
"domain" : null,
"defaultValue" : null
},
{
"name" : "STATE_NAME",
"type" : "esriFieldTypeString",
"alias" : "STATE_NAME",
"sqlType" : "sqlTypeOther", "length" : 25,
"domain" : null,
"defaultValue" : null
},
{
"name" : "STATE_CITY",
"type" : "esriFieldTypeString",
"alias" : "STATE_CITY",
"sqlType" : "sqlTypeOther", "length" : 7,
"domain" : null,
"defaultValue" : null
},
{
"name" : "TYPE",
"type" : "esriFieldTypeString",
"alias" : "TYPE",
"sqlType" : "sqlTypeOther", "length" : 25,
"domain" : null,
"defaultValue" : null
},
{
"name" : "CAPITAL",
"type" : "esriFieldTypeString",
"alias" : "CAPITAL",
"sqlType" : "sqlTypeOther", "length" : 1,
"domain" : null,
"defaultValue" : null
},
{
"name" : "ELEVATION",
"type" : "esriFieldTypeSmallInteger",
"alias" : "ELEVATION",
"sqlType" : "sqlTypeOther",
"domain" : null,
"defaultValue" : null
},
{
"name" : "POP1990",
"type" : "esriFieldTypeInteger",
"alias" : "POP1990",
"sqlType" : "sqlTypeOther",
"domain" : null,
"defaultValue" : null
},
{
"name" : "HOUSEHOLDS",
"type" : "esriFieldTypeInteger",
"alias" : "HOUSEHOLDS",
"sqlType" : "sqlTypeOther",
"domain" : null,
"defaultValue" : null
},
{
"name" : "MALES",
"type" : "esriFieldTypeInteger",
"alias" : "MALES",
"sqlType" : "sqlTypeOther",
"domain" : null,
"defaultValue" : null
},
{
"name" : "FEMALES",
"type" : "esriFieldTypeInteger",
"alias" : "FEMALES",
"sqlType" : "sqlTypeOther",
"domain" : null,
"defaultValue" : null
},
{
"name" : "GLOBALID",
"type" : "esriFieldTypeGlobalID",
"alias" : "GLOBALID",
"sqlType" : "sqlTypeOther", "length" : 38,
"domain" : null,
"defaultValue" : null
}
],
"features" : [
{
"attributes" : {
"OBJECTID" : 69,
"CITY_FIPS" : "66000",
"CITY_NAME" : "San Diego",
"STATE_FIPS" : "06",
"STATE_NAME" : "California",
"STATE_CITY" : "0666000",
"TYPE" : "city",
"CAPITAL" : "N",
"ELEVATION" : 42,
"POP1990" : 1110549,
"HOUSEHOLDS" : 406096,
"MALES" : 566464,
"FEMALES" : 544085,
"GLOBALID" : "e2c94f46-17d3-4459-9675-600ae69f4d1f"
},
"geometry" :
{
"x" : -117.13666926135465,
"y" : 32.814997725516207
}
}
]
},
{
"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]
}
]
}