Query (Feature Service)

URL:: https://<root>/<serviceName>/FeatureServer/query
Methods:: GET
Required Capability:: Query
Version Introduced:: 10.1

Description

The query operation queries a feature service resource and returns either a feature set for each layer in the query, 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.

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

New at 11.0

At this release, feature services can be published from a Google BigQuery data source using ArcGIS Pro 3.0 or later.

New at 10.9

A new parameter, timeReferenceUnknownClient , has been added at 10.9. Setting timeReferenceUnknownClient as true indicates that the client is capable of working with date field data values that are not in UTC. For more information on this parameter, see the Request 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
`layerDefs`	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. For more information on WHERE clauses, see the SQL 92 WHERE clause section below. Syntax Use dark colors for code blocksCopy 1 2 3 4 5 6 7 8 //Simple syntax. Layer IDs are returned by the feature service resource layerId1:layerDef1;layerId2:layerDef2 //JSON representation for Layer Definitions. Layer IDs are returned by the feature service resource { "<layerId1>" : "<layerDef1>" , "<layerId2>" : "<layerDef2>" } //JSON representation of a layer definition to specify output fields. Layer IDs are returned by the feature service resource [{ "layerId" : <layerId1>,"where": "<where clause>", "outfields": "<field1>,<field2>"},{"layerId" : <layerId2>,"where": "<where clause>", "outfields": "<field1>,<field2>"}] Example Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 //Simple example 0:POP2000 > 1000000;5:AREA > 100000 //JSON representation for Layer Definitions {"0":"POP2000 > 1000000","5":"AREA > 100000"} //JSON representation of a layer definition to specify output fields [{"layerId" : 0, "where" : "OBJECTID<100", "outFields" : "*"}, {"layerId" : 1, "where" : "OBJECTID<323", "outFields" : "OBJECTID,CREATOR"}]`
`geometry`	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, you can specify the geometry of envelopes and points with a simple 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`	The type of geometry specified by the `geometry` parameter. The geometry type can be an envelope, a point, a line, or a polygon. The default geometry type is an envelope. Values: `esriGeometryPoint \| esriGeometryMultipoint \| esriGeometryPolyline \| esriGeometryPolygon \| esriGeometryEnvelope`
`inSR`	The spatial reference of the input `geometry` . The spatial reference can be specified as either a well-known ID or a spatial reference JSON object. If `inSR` is not specified, the geometry is assumed to be in the spatial reference of the map.
`spatialRel`	The spatial relationship to be applied to 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` \| `esriSpatialRelRelation`
`time`	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`	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 service.
`gdbVersion`	The geodatabase version to query. This parameter applies only if the `hasVersionedData` property of the service and the `isDataVersioned` property of the layers 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`	The historic moment to query. This option was added at 10.5 and works with ArcGIS Server services only. 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 Use dark colors for code blocksCopy `1 historicMoment=<Epoch time in milliseconds>` Example Use dark colors for code blocksCopy `1 historicMoment=1199145600000`
`returnGeometry`	If `true` , the result includes the geometry associated with each feature returned. The default is `true` . Values: `true` \| `false`
`maxAllowableOffset`	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, `maxAllowableOffset` is assumed to be in the unit of the spatial reference of the map. Example Use dark colors for code blocksCopy `1 maxAllowableOffset=2`
`returnIdsOnly`	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` as `true` and subsequently requesting feature sets for subsets of object IDs. Values: `true` \| `false`
`returnCountOnly`	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`	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` properties is `true` . Values: `true` \| `false`
`returnM`	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` properties is `true` . Values: `true` \| `false`
`geometryPrecision`	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). Use dark colors for code blocksCopy `1 geometryPrecision=3`
`multipatchOption`	How the geometry of a multipatch feature will be returned. This parameter only applies if the layers in the service have the `esriGeometryMultipatch` geometry type. When set to `xyFootprint` , the x,y footprint of each multipatch geometry will be returned in the result. When set to `stripMaterials` , the multipatch geometry will be returned without materials (for example, colors and textures). When set as `embedMaterials` , the multipatch geometry will be returned with materials embedded in it. If set to `externalizeTextures` , the multipatch geometry will be returned with materials, but the textures will be returned by reference. Note If `returnGeometry` is `false` , specifying the `multipatchOption` is not required. Values: `xyFootprint` \| `stripMaterials` \| `embedMaterials` \| `externalizeTextures`
`returnTrueCurves` (Optional)	This option was added at 10.5. When set to `true` , the query returns true curves in output geometries. When set to `false` , curves are converted to densified polylines or polygons. The default value is `false` . Values: `true` \| `false`
`sqlFormat`	The `sqlFormat` parameter can be either standard SQL-92 `standard` or it can use the native SQL of the underlying data store `native` . The default is `none` , which means the `sqlFormat` depends on the `useStandardizedQuery` parameter. Note The SQL format `native` is supported only when `useStandardizedQuery=false` . Values: `none` \| `standard` \| `native`
`timeReferenceUnknownClient`	Setting `timeReferenceUnknownClient` as `true` indicates that the client is capable of working with data values that are not in UTC. If its not set to `true` , and the service layer's `datesInUnknownTimeZone` property is `true` , then an error is returned. The default is `false` Its possible to define a service's time zone of date fields as unknown. Setting the time zone as unknown means that date values will be returned as-is from the database, rather than as date values in UTC. Non-hosted feature services can be set to use an unknown time zone using ArcGIS Server Manager. Setting the time zones to unknown also sets the `datesInUnknownTimeZone` layer property as `true` . Currently, hosted feature services do not support this setting. This setting does not apply to editor tracking date fields which are stored and returned in UTC even when the time zone is set to unknown. Most clients released prior to ArcGIS Enterprise 10.9 will not be able to work with feature services that have an unknown time setting. The `timeReferenceUnknownClient` parameter prevents these clients from working with the service in order to avoid problems.. Setting this parameter to `true` indicates that the client is capable of working with unknown date values that are not in UTC. Note ArcGIS Pro 2.7 or newer can work with these feature services. Value: `true` \| `false`
`f`	The response format. The default response format is `html` . Values: `html \| json` (default, when `returnIdsOnly=false` and `returnCountOnly=false` ) Values: `html \| json` (when `returnIdsOnly=true` or `returnCountOnly=true` )

SQL 92 WHERE clause

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. Here is a list of supported SQL 92 with spatiotemporal based feature services:

Use dark colors for code blocksCopy
<COLUMN | LITERAL> '<=' | '>=' | '<' | '>' | '=' | '<>' <COLUMN | LITERAL>
<BOOLEAN EXPRESSION> AND | OR <BOOLEAN EXPRESSION>
NOT <BOOLEAN EXPRESSION>
<COLUMN> IS [ NOT ] NULL
<COLUMN> [ NOT ] LIKE <STRING>
<COLUMN> [ NOT ] IN ( <LITERAL, <LITERAL>, ... )
<COLUMN> [ NOT ] BETWEEN <COLUMN | LITERAL> AND <COLUMN | LITERAL>

Examples

Use dark colors for code blocksCopy
where=POP2000 > 350000

where=CITY_NAME = 'Barrington'

Date-Time Queries

In general, the dateFieldsTimeReference property of the feature service layer identifies the time zone that all dates are stored in. The exception cases involve editor tracking date fields and time aware layer time zones.

When you are working with your data, you need to consider the time zone of the fields that you are working with. If you are querying a date type field and dateFieldsTimeReference is set to a specific time zone, make sure your WHERE clause issues the time in that specific time zone. For example, if you want to return all the records that match 1:00 p.m. on February 9, 2015, Pacific standard time, your WHERE clause would be as follows:

Querying records in PST

Use dark colors for code blocksCopy
where=pacific_time_date_field = TIMESTAMP '2015-02-09 13:00:00'

However, it is possible to have up to three different time zones defined on your service. If your query includes dates from the editor tracking fields or the time aware fields, you need to make sure you submit the query in their respective time zones. The time zones for these fields can be found in the properties mentioned above. If the dateFieldsTimeReference is null the data is assumed to be in UTC, and if it is Unknown the time zone is assumed to be undefined. The example below demonstrates how to query three date fields that have three different times zones. When querying fields in different time zones, you need to make sure the time you use corresponds with the time zone of the date field. There is a date field in PST, one in EST, and the editor tracking field created_date in UTC:

Querying records in three different time zones

Use dark colors for code blocksCopy
where = (DateTime_PST = TIMESTAMP '2012-01-01 15:20:00' AND (DateTime_EST = TIMESTAMP '2012-01-01 18:20:00' AND created_date = TIMESTAMP '2012-01-01 22:20:00')

Although you issue local time in your WHERE clause, the query operation always returns date values in UTC. You can set the date fields time zone, which shows up in the dateFieldsTimeReference property of the feature service layer either during publishing or in the ArcGIS Server Manager after publishing. In the Server Manager, navigate to service you wish to edit and click on the Parameters tab to update the time zone information. If the dateFieldsTimeReference property is not set, it will show up as null and the data will be assumed to be in UTC. In this case make sure you issue your WHERE clause in UTC.

As of ArcGIS Pro 3.1 and ArcGIS Enterprise 10.9, there is a new option when defining the time zone during publishing. If you don't want to define a time zone at all (not even UTC), you can set it to Unknown. Using the Unknown time zone makes it so that there is no translation done when the query operation submits and returns date values, they are stored and returned as is. This is particularly useful if you have data which spans multiple time zones.

SQL Format

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

sqlFormat value	useStandardizedQuery=true	useStandardizedQuery=false
standard (sql'92)	Yes	Yes
native (native DBMS sql)	Not supported	Yes
none	Only sql'92 (means standard)	Only DBMS native SQL (native)

Example usage

Below is a sample request URL used to demonstrate how to query layers with the IDs of 0 and 1:

Use dark colors for code blocksCopy
https://machine.domain.com/webadaptor/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 examples

Example one

The syntax example below demonstrates the structure of the response returned by query when returnCountOnly is false :

Use dark colors for code blocksCopy
{
  "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>
      ]
    }
  ]
}

Example two

The syntax example below demonstrates the structure of the response returned by query when returnCountOnly is true .

Use dark colors for code blocksCopy
{
  "layers": [
    {
      "id": <layerId1>,
      "count": <count>
    },
    {
      "id": <layerId2>,
      "count": <count>
    }
  ]
}

Example three

The syntax example below demonstrates the structure of the response returned by query when returnIdsOnly is true .

Use dark colors for code blocksCopy
{
  "layers":[
    {
      "id": <layerId1>,
      "objectIdFieldName": <objectIdFieldName>,
      "objectIds": [
        <objectId1>,
        <objectId2>,
        <objectId3>
      ]
    },
    {
      "id": <layerId2>,
      "objectIdFieldName": <objectIdFieldName>,
      "objectIds": [
        <objectId1>,
        <objectId2>,
        <objectId3>
      ]
    }
  ]
}

JSON Response examples

Example one

The response below demonstrates the response returned by query when returnIdsOnly is false and returnCountOnly is false .

Use dark colors for code blocksCopy
{
  "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": []
    }
  ]
}

Example two

The response below demonstrates the response returned by query when returnIdsOnly is false , returnCountOnly is false , and geometryPrecision is 4 .

Use dark colors for code blocksCopy
{
  "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": []
    }
  ]
}

Example three

The response below demonstrates the response returned by query when returnCountOnly is true

Use dark colors for code blocksCopy
{
  "layers": [
    {
      "id" : 1,
      "count": 2
    },
    {
      "id" : 2,
      "count":0
    }
  ]
}

Example four

The response demonstrates the response returned by query when returnIdsOnly is true .

Use dark colors for code blocksCopy
{
  "layers": [
    {
      "id": 0,
      "objectIdFieldName": "OBJECTID",
      "objectIds": [5]
    },
    {
      "id": 1,
      "objectIdFieldName": "OBJECTID",
      "objectIds": [1]
    }
  ]
}