Query (Feature Service)

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.

NoteNote:

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:

  • 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 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.

NoteNote:

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

NoteNote:
  • The SQL format native is supported only when useStandardizedQuery=false.

The table summarizes the sqlFormat parameter and what you would expect from the query API.

useStandardizedQuery=true

useStandardizedQeury=false

standard (sql'92)

native (native DBMS sql)

x(not supported)

[none]

Only sql'92 (means standard)

Only DBMS native SQL (native)

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]
  }
 ]
}