Query (Feature Service)

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.

NoteNote:

If the query results include an empty feature set, the field set is not returned.

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.

NoteNote:

Date field values in a query response from a Google BigQuery feature service are assumed to be in UTC. Values from database fields of the timestamp type are accurate as they are returned from the database in UTC. Values from database fields of the time, date, and datetime type may not be accurate as they may not be returned from the database in UTC. To avoid potential issues, feature services can be published from ArcGIS Pro that exclude the non-UTC time, date, and datetime fields.

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

//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

//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

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

historicMoment=<Epoch time in milliseconds>

Example

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

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

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.

NoteNote:

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.

NoteNote:

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.

NoteNote:

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:

<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

where=POP2000 > 350000

where=CITY_NAME = 'Barrington'

The dateFieldsTimeReference property of the feature service identifies the time zone that all dates are stored in. If you are querying a date type field and have dateFieldsTimeReference 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:

where=pacific_time_date_field = DATE '2015-02-09 13:00:00'

Although you issue local time in your WHERE clause, the query operation always returns date values in UTC. You can set the dateFieldsTimezoneID property by setting the Time Zone property in the Service Configuration Parameters tab, when you publish the service. See publish feature service help for more information. If you don't have dateFieldsTimezoneID set, Query does not return date values in UTC, but instead returns them as-is.

NoteNote:

the INTERVAL syntax can be used in place of the date-time queries and will be standardized across all map and feature services. For more information on the INTERVAL syntax, see Querying Feature Services: Date-Time Queries.

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:

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:

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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

{
  "layers": [
    {
      "id" : 1,
      "count": 2
    },
    {
      "id" : 2,
      "count":0
    }
  ]
}

Example four

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

{
  "layers": [
    {
      "id": 0,
      "objectIdFieldName": "OBJECTID",
      "objectIds": [5]
    },
    {
      "id": 1,
      "objectIdFieldName": "OBJECTID",
      "objectIds": [1]
    }
  ]
}