Query (Feature Service)
- URL:http://<featureservice-url>/query
- Required Capability:Query
- Version Introduced:10.1
Description
This operation is supported at 10.1 and later.
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).
While there is a limit to the number of features included in the response (see the maxRecordCount property of the feature service), there is no limit to 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 include their geometries. The records for tables do not.
If the query results include an empty feature set, the fields set is not returned.
You can provide arguments to the query operation as query parameters defined in the parameters table below.
New at 10.6.1
Added query options for multipatch data with stripMaterials, embedMaterials, and externalizeTextures.
New at 10.5
The feature service layer Query operation supports the returnTrueCurves, historicMoment and sqlFormat parameters.
New at 10.1 SP1
The Feature Service Query operation supports spatialRel and time parameters.
The Feature Service Query operation supports a new JSON representation of the layerDefs parameter with an 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 (where clauses) for those layers. A definition expression for a layer that is published with the service will always be honored. SQL 92 where clause syntax on the fields in the layer is supported for most data sources. Some data sources have restrictions on what is supported. Hosted feature services in ArcGIS Enterprise running on a spatiotemporal data source have restrictions on what is supported; they only support a subset of SQL 92. For example, spatiotemporal based feature services support the like operator but do not support the not like operator or field equivalency expressions like field1 = field2. Here is a list of supported SQL 92 with spatiotemporal based feature services: ( '<=' | '>=' | '<' | '>' | '=' | '!=' | '<>' | LIKE ) (AND | OR) (IS | IS_NOT) (IN | NOT_IN) ( '(' ( expr ( ',' expr )* )? ')' ) COLUMN_NAME BETWEEN LITERAL_VALUE AND LITERAL_VALUE 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 a 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, and so on. 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. Example: time=null, 1230768000000 | ||||||||||||
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: The 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 | ||||||||||||
historicMoment | This option was added at 10.5 and works with ArcGIS Server services only. Description: The historic moment to query. This parameter applies only if the supportsQueryWithHistoricMoment property of the layers being queried is set to true. This setting is provided in the layer resource. If historicMoment is not specified, the query will apply to the current features. Syntax: historicMoment=<Epoch time in milliseconds> Example: historicMoment=1199145600000 | ||||||||||||
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. 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 to the number of features included in the feature set response, there is no limit to 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 are 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 layer's hasZ property is true. | ||||||||||||
returnM | This option was added at 10.1. Description: If true, M values are 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 layer's 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 | ||||||||||||
multipatchOption | Description: This option dictates how the geometry of a multipatch feature will be returned. Values: <xyFootprint | stripMaterials | embedMaterials | externalizeTextures> This parameter only applies if the layers in the service have "geometryType": "esriGeometryMultipatch". If multipatchOption = xyFootprint, the xy footprint of each multipatch geometry will be returned in the result. If multipatchOption = stripMaterials, the multipatch geometry will be returned without materials (i.e. colors and textures). If multipatchOption = embedMaterials, the multipatch geometry will be returned with materials embedded in it. If multipatchOption = externalizeTextures, the multipatch geometry will be returned with materials, but the textures will be returned by reference. Note: If returnGeometry = false, specifying the multipatchOption is not required. | ||||||||||||
returnTrueCurves | This option was added at 10.5. Description: Optional parameter which is false by default. When set to true, returns true curves in output geometries. When set to false, curves are converted to densified polylines or polygons. Values: true|false Example: trueCurveClient=true | ||||||||||||
sqlFormat | Description: The sqlFormat parameter can be either standard SQL92 standard or it can use the native SQL of the underlying datastore native. The default is none which means the sqlFormat depends on useStandardizedQuery parameter. Values: none | standard | native Note:
The table summarizes the sqlFormat parameter and what you would expect from the query API.
Example: sqlFormat=standard |
Example usage
Example 1: Query layer ids 0 and 1:
http://services.myserver.com/OrgID/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]
}
]
}