Query (Feature Service/Layer)

Description

The query operation is performed on a feature service layer resource. The result of this operation is either a feature set or an array of feature IDs (if returnIdsOnly is set to true) and/or a result extent (if returnExtentOnly is set to true).

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.

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.

NoteNote:

Query with returnDistinctResults defaults to using spatial relation intersects irrespective of a user-selected spatial relation.

For time-aware layers, you can use the time parameter to specify the time instant or the time extent to query.

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

To use pagination with aggregated queries (queries using either returnDistinctValues or outStatistics with groupByFieldsForStatistics) on hosted feature services in ArcGIS Enterprise, the supportsPaginationOnAggregatedQueries property must be true on the layer. Hosted feature services using a spatiotemporal data store do not currently support pagination on aggregated queries.

Features added throughout earlier releases

10.8.1

The layer query operation supports percentile as a statisticType when using outStatistics for feature services published from ArcGIS Pro that reference enterprise geodatabase data. Layers that support percentiles include the supportsPercentileStatistics property as true, found in the advancedQueryCapabilities layer object.

Multipatch data can be queried with multipatchOption set as externalizeTextures and f as pbf for feature services published from ArcGIS Pro.

Non-hosted feature services published from ArcGIS Pro support an optimization for getting a layer's row count. By setting where as 9999=9999 and returnCountOnly as true, the result is an approximate count that is returned very quickly. For accurate, but slower to return, row counts, use any other filter (e.g. where: 1=1). This is only supported when a layer has both isDataVersioned and isDataArchived as false.

10.8

The layer query operation supports percentile as a statisticType when using outstatistic for hosted feature services in ArcGIS Online or ArcGIS Enterprise when run on a relational data store. Layers that support percentiles include the advancedQueryCapabilities object property supportsPercentileStatistics as true.

10.7

  • Feature services now support the protocol buffer (pbf) query format. This format is supported on feature service layers published from ArcGIS Pro that reference data in a registered enterprise geodatabase. The supportedQueryFormats layer property will list pbf if it is available on the layer.

10.6.1

  • The feature service layer Query operation supports the havingClause parameter.
  • The feature service layer Query operation supports querying the count of distinct features within a field using the returnDistinctValues and returnCountOnly parameters.
  • Query support for coordinate quantization using returnCentroid, returnExceededLimitFeatures, and resultType when supportsCoordinateQuantization = true.
  • Added query options for multipatch data with stripMaterials, embedMaterials, and externalizeTextures.
  • Query support using the INTERVAL syntax, which can be used in place of the date-time queries and will be standardized across all map and feature services.
NoteNote:

For feature services published to an ArcGIS Enterprise federated server with data stored in a registered enterprise geodatabase, when requesting quantized geometry, if returnTrueCurves = true, the curves will be densified in the quantized results.

10.5

  • The feature service layer Query operation supports the returnTrueCurves, historicMoment, and sqlFormat parameters.

10.3.1

  • The feature service layer Query operation supports the returnTrueCurves parameter.
  • The exceededTransferLimit property is now included in the JSON response when paging through a query result with the resultOffset and resultRecordCount parameters. When exceededTransferLimit is true, it indicates there are more query results and you can continue to page through the results. When exceededTransferLimit is false, it indicates that you have reached the end of the query results.

  • When not using the resultOffset and resultRecordCount parameters, the exceededTransferLimit property may also be included in the query results. In this case, the property will be true only if the number of records exceeds the maximum number configured by the server administrator.
  • In some cases when using the resultOffset and resultRecordCount parameters, the exceededTransferLimit property may be included in the query results even though the value specified in the resultRecordCount has not been exceeded. This is due to internal spatial index filtering of the query results. For this reason, you should always rely on the exceededTransferLimit property to determine if you should page through results rather than relying on the number of results returned from each page. In some extreme cases, zero results can be returned but the exceededTransferLimit property will be returned. In these cases, you should continue paging through your results until exceededTransferLimit is no longer returned.
  • If using orderByFields with the resultOffset and resultRecordCount parameters to paginate through an ordered set of rows, make sure to set the orderByFields such that the order is deterministic. For example, if you need to order by type and multiple rows can have the same type values, set the orderByFields to be type,objectid.

10.3

  • Supports pagination in a query layer. Use the resultOffset and resultRecordCount parameters to page through a query result.
  • Note that when you pass in one of these two parameters and orderByFields is left empty, the map service uses the object-id field to sort the result. For a query layer with a pseudocolumn as the object-id field (for example, FID), you must provide orderByFields; otherwise, the query fails.

Request parameters

Parameter

Details

where

A WHERE clause for the query filter.

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 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 such as field1 = field2. Below 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

For information on how to format time and date information, see the Date-time queries section below.

Examples

where=POP2000 > 350000

where=CITY_NAME = 'Barrington'

objectIds

The object IDs of this layer or table to be queried.

NoteNote:

There might be a drop in performance if the layer/table data source resides in an enterprise geodatabase and more than 1,000 objectIds are specified.

Syntax: objectIds=<objectId1>, <objectId2>

Example: objectIds=37, 462

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 as a spatial reference JSON object. If the inSR is not specified, the geometry is assumed to be in the spatial reference of the layer.

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

relationParam

The spatial relate function that can be applied while performing the query operation. An example for this spatial relate function is "FFFTTT***". For more information on this spatial relate function, see the documentation for the spatial relate function.

NoteNote:

This parameter is not supported in the ArcGIS Online hosted service case.

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

distance

The buffer distance for the input geometries. The distance unit is specified by units. For example, if the distance is 100, the query geometry is a point, units is set to meters, and all points within 100 meters of the point are returned. The geodesic buffer is created based on the datum of the output spatial reference if it exists. If there is no output spatial reference, the input geometry spatial reference is used. Otherwise, the native layer spatial reference is used to generate the geometry buffer used in the query. This parameter only applies if supportsQueryWithDistance is true.

Syntax

distance=<distance>

Example

distance=100
units

The unit for calculating the buffer distance. If unit is not specified, the default will be esriSRUnit_Foot when querying feature services in ArcGIS Enterprise, and esriSRUnit_Meter when querying feature services in ArcGIS Online. This parameter only applies if supportsQueryWithDistance is true.

Values: esriSRUnit_Meter | esriSRUnit_StatuteMile | esriSRUnit_Foot | esriSRUnit_Kilometer | esriSRUnit_NauticalMile | esriSRUnit_USNauticalMile

outFields

The list of fields to be included in the returned result set. This list is a comma-delimited list of field names. You can also specify the wildcard "*" as the value of this parameter. In this case, the query results include all the field values.

Example

//Standard usage
outFields=AREANAME,ST,POP2000

//Wildcard usage
outFields=*
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 outSR. If outSR is not specified, maxAllowableOffset is assumed to be in the unit of the spatial reference of the map.

Example

maxAllowableOffset=2
geometryPrecision

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

When using outSR with pbf, the pbf format will use coordinate quantization for layer queries. When an output spatial reference is not provided for a query operation, the feature service derives coordinate quantization parameters from the layer’s spatial reference. If the precision in the layer’s spatial reference is inadequate for the client application’s use, it should pass in a spatial reference with suitable precision as the output spatial reference. If the layer’s source spatial reference has the desired precision and it is suitable for the client’s use, the client can use the source layer's spatial reference as the output spatial reference.

havingClause

This option was added at 10.6.1. This option is a condition used with outStatistics that limits the query result to groups that satisfy the aggregation function used. The havingClause parameter is used with the groupBy and outStatistics parameters and allows you to filter results from outStatistics. This parameter applies only if the supportsHavingClause property of the layer is true.

NoteNote:

The havingClause parameter takes aggregate functions such as AVG(<fieldname>). It does not support the outStatisticFieldName from the outStatistics parameter. For example, the having clause can't be set to >1000; it must be set as AVG(housing_price > 1000. You can also use statistics functions in the having clause that are not necessarily in the outStatistics parameter. For example, the following returns the average housing price for neighborhoods with more than 1,000 homes:

outStatistics=[{"statisticType":"AVG","onStatisticField":"housing_price","outStatisticFieldName":"avgHousePrice"}], havingClause=COUNT(houses) > 1000

Values: AVG | COUNT | SUM | STDDEV | MIN | MAX | VAR

NoteNote:

havingClause must be used with groupBy and outStatistics.

gdbVersion

The geodatabase version to query. This parameter applies only if the isDataVersioned property of the layer is true. If this is not specified, the query will apply to the published map’s version.

Syntax: gdbVersion=<version>

Example: gdbVersion=SDE.DEFAULT

returnDistinctValues

If true, it returns distinct values based on the fields specified in outFields. This parameter applies only if the supportsAdvancedQueries property of the layer is true. This parameter can be used with returnCountOnly to return the count of distinct values of subfields.

NoteNote:

Make sure to set returnGeometry to false when returnDistinctValues is true. Otherwise, reliable results will not be returned.

Values: true | false

returnIdsOnly

If true, the response only includes an array of object IDs. Otherwise, the response is a feature set. The default is false. When objectIds are specified, setting this parameter to true is invalid.

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

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. This option supersedes the returnIdsOnly parameter. If returnCountOnly = true, the response will return both the count and the extent. This parameter can be used with returnDistinctValues to return the count of distinct values of subfields.

Values: true | false

returnExtentOnly

This option was added at 10.3. If true, the response only includes the extent of the features that would be returned by the query. If returnCountOnly=true, the response will return both the count and the extent. The default is false. This parameter applies only if the supportsReturningQueryExtent property of the layer is true.

NoteNote:

At 10.3, this option is only available for hosted feature services. At 10.3.1, this option is available for hosted and nonhosted feature services.

Values: true | false

orderByFields

One or more field names on which the features/records need to be ordered. Use ASC or DESC for ascending or descending, respectively, following every field to control the ordering. orderByFields defaults to ASC (ascending order) if <ORDER> is unspecified. orderByFields is supported on only those layers/tables that indicate supportsAdvancedQueries is true.

NoteNote:
If supportsOrderByOnlyOnLayerFields is true, only fields from the layer's fields array can be used with the orderByFields parameter. For example, the outStatisticfieldName from outStatistics can't be used if supportsOrderByOnlyOnLayerFields is true.

Syntax

orderByFields=field1 <ORDER>, field2 <ORDER>, field3 <ORDER>

Example

orderByFields=STATE_NAME ASC, RACE DESC, GENDER
groupByFieldsForStatistics

One or more field names on which the values need to be grouped for calculating the statistics. groupByFieldsForStatistics is valid only when the outStatistics parameter is used.

Syntax

groupByFieldsForStatistics=field1, field2

Example

groupByFieldsForStatistics=STATE_NAME, GENDER
outStatistics

The definitions for one or more field-based statistics to be calculated. This parameter is supported only on layers/tables that indicate supportsStatistics is true. When using outStatistics, the only other parameters that can be used are groupByFieldsForStatistics, orderByFields, time, and where. For information on how to use percentile statisticType, see the Percentile statistic type section below.

NoteNote:

If outStatisticFieldName is empty or missing, the map server assigns a field name to the returned statistic field. A valid field name can only contain alphanumeric characters and an underscore. If the outStatisticFieldName is a reserved keyword of the underlying DBMS, the operation can fail. Try specifying an alternative outStatisticFieldName.

Syntax

[
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var>",
    "onStatisticField": "Field1", 
    "outStatisticFieldName": "Out_Field_Name1"
  },
  {
    "statisticType": "<count | sum | min | max | avg | stddev | var>",
    "onStatisticField": "Field2",
    "outStatisticFieldName": "Out_Field_Name2"
  }  
]

Example

[
  {
    "statisticType": "sum",
    "onStatisticField": "GENDER",
    "outStatisticFieldName": "PopulationByGender"
  },
  {
    "statisticType": "avg",
    "onStatisticField": "INCOME",
    "outStatisticFieldName": "AverageIncome"
  }
]
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 the layer's hasZ property is true.

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 the layer's hasM property is true .

multipatchOption

This option dictates how the geometry of a multipatch feature will be returned. This parameter only applies if the layer's geometryType property is esriGeometryMultiPatch.

NoteNote:

If returnGeometry is set to false, specifying the multipatchOption is not required.

If multipatchOption is set to xyFootprint, the x,y footprint of each multipatch geometry will be returned in the result. If multipatchOption is set to stripMaterials, the multipatch geometry will be returned without materials (for instance, colors and textures). If multipatchOption is set to embedMaterials, the multipatch geometry will be returned with materials embedded in it. If multipatchOption is set to externalizeTextures, the multipatch geometry will be returned with materials, but the textures will be returned by reference.

Values: xyFootprint | stripMaterials | embedMaterials | externalizeTextures

resultOffset

Introduced at 10.3. This option can be used for fetching query results by skipping the specified number of records and starting from the next record (that is, resultOffset + 1). The default is 0. This parameter only applies if supportsPagination is true. You can use this option to fetch records that are beyond maxRecordCount.

Example

//Retrieve next 100 records
resultRecordCount=10
resultRecordCount

Introduced at 10.3. This option can be used for fetching query results up to the resultRecordCount specified. When resultOffset is specified but this parameter is not, the map service defaults it to maxRecordCount. The maximum value for this parameter is the value of the layer's maxRecordCount property. The minimum value entered for this parameter cannot be below 1. This parameter only applies if supportsPagination is true.

Example

resultRecordCount=10
quantizationParameters

This option is supported by all feature services in ArcGIS Enterprise at 10.6.1. This is a JSON object used to project the geometry onto a virtual grid, likely representing pixels on the screen. The properties of the JSON object include extent, mode, originPosition, and tolerance. For more information, see the Quantization parameters JSON properties section below.

NoteNote:

This parameter only applies if supportsCoordinatesQuantization is true.

Examples

//upperLeft origin position
{"mode":"view","originPosition":"upperLeft","tolerance":1.0583354500042335,"extent":{"type":"extent","xmin":-18341377.47954369,"ymin":2979920.6113554947,"xmax":-7546517.393554582,"ymax":11203512.89298139,"spatialReference":{"wkid":102100,"latestWkid":3857}}}

//lowerLeft origin position
{"mode":"view","originPosition":"lowerLeft","tolerance":1.0583354500042335,"extent":{"type":"extent","xmin":-18341377.47954369,"ymin":2979920.6113554947,"xmax":-7546517.393554582,"ymax":11203512.89298139,"spatialReference":{"wkid":102100,"latestWkid":3857}}}
returnCentroid

Used to return the geometry centroid associated with each feature returned. If true, the result includes the geometry centroid. The default is false. Currently, this parameter is not supported for polygon data and is ignored for count and objectID queries. This parameter is only supported on layer-level queries.

NoteNote:

The layer metadata returns supportsReturningGeometryCentroid in the advancedQueryCapabilities metadata object. The absence of the supportsReturningGeometryCentroid property means that the server does not support the returnCentroid parameter. Line and point data will return supportReturningGeometryCentroid as false.

Values: true | false

resultType

(Optional)

The resultType parameter can be used to control the number of features returned by the query operation. The tile value is used when the client is using a virtual tiling scheme when querying features, which works similarly to tiles in a tiled map service layer. The standard value is used with a nontiled query where the client will send only one query for the full extent. Support for this parameter is advertised on the layer metadata in the supportsQueryWithResultType property. For additional information on the resultType parameter and how it interacts with max record counts, see the Result type and max record count.

Values: none | standard | tile

historicMoment

This option was added at 10.5 and works with ArcGIS Server services only. This is the historic moment to query. This parameter applies only if the layer is archiving enabled and the supportsQueryWithHistoricMoment property is set to true. This property 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
returnTrueCurves

Introduced at 10.5. When set to true, it returns true curves in output geometries. When set to false, curves are converted to densified polylines or polygons. The default is false.

NoteNote:

For feature services published to an ArcGIS Enterprise federated server with data stored in a registered enterprise geodatabase, when requesting quantized geometry, if returnTrueCurves = true, the curves will be densified in the quantized results.

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. For more information on formatting, see the SQL format section below.

Values: none | standard | native

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

As of 10.6.1, this option is supported by most feature services, except for feature services published using a spatiotemporal data store. This parameter is true by default. When set to true, features are returned even when the results include "exceededTransferLimit": true.

When set to false and querying with resultType set to tile, features are not returned when the results include "exceededTransferLimit": true. This allows a client to find the resolution in which the transfer limit is no longer exceeded without making multiple calls.

Values: true | false

datumTransformation

Introduced at 10.8. This parameter applies a datum transformation while projecting geometries in the results when outSR is different than the layer's spatial reference. When specifying transformations, you need to think about which datum transformation best projects the layer (not the feature service) to the outSR and sourceSpatialReference property in the layer resource report. For a list of valid datum transformation ID values and well-known text strings, see Coordinate systems and transformations (values applicable for ArcGIS Desktop, ArcGIS Enterprise, ArcGIS Pro, and ArcGIS Runtime). For more information on datum transformations, see the transformation parameter in the Project operation.

NoteNote:

The supportsQueryWithDatumTransformation layer property in advancedQueryCapabilities will be true if this parameter is supported.

Syntax

//Syntax to apply a simple transformation
datumTransformation=<wkid>

//Syntax to apply a simple transformation
datumTransformation={"wkt": "<WKT>"}

//Syntax to apply a composite transformation
datumTransformation={"geoTransforms":[{"wkid":<id>,"forward":<true|false>},{"wkt":"<WKT>","forward":<true|false>}]}

Example

//Applies a simple transformation
datumTransformation=1623

//Applies a composite transformation
datumTransformation={
  "geoTransforms":[
    {
      "wkid":1088,
      "transformForward": true
    },
    {
      "wkid": "GEOGTRAN[\"S_JTSK_To_WGS_1984_1\",GEOGCS[\"GCS_S_JTSK\",DATUM[\"D_S_JTSK\",SPHEROID[\"Bessel_1841\",6377397.155,299.1528128]],
        PRIMEM[\"Greenwich\",0.0],UNIT[\"Degree\",0.0174532925199433]],GEOGCS[\"GCS_WGS_1984\",DATUM[\"D_WGS_1984\",SPHEROID[\"WGS_
        1984\",6378137.0,298.257223563]],PRIMEM[\"Greenwich\",0.0],UNIT[\"Degree\",0.0174532925199433]],METHOD[\"Position_Vector\"],
        PARAMETER[\"X_Axis_Translation\",570.8],PARAMETER[\"Y_Axis_Translation\",85.7],PARAMETER[\"Z_Axis_Translation\",462.8],
        PARAMETER[\"X_Axis_Rotation\",4.998],PARAMETER[\"Y_Axis_Rotation\",1.587],PARAMETER[\"Z_Axis_Rotation\",5.261],
        PARAMETER[\"Scale_Difference\",3.56]]",
      "transformForward":false
    }
  ]
}
spatialRel

Introduced at 10.8. This parameter applies for hosted feature services running on a spatiotemporal data store if sqlParserVersion contains ES.

Point layers require either an envelope or polygon input geometry and support the following values:

Values: esriSpatialRelIntersects | esriSpatialRelEnvelopeIntersects | esriSpatialRelIndexIntersects | esriSpatialRelWithin

Polygon or polyline layers support the following values:

Values: esriSpatialRelIntersects | esriSpatialRelContains | esriSpatialRelEnvelopeIntersects | esriSpatialRelIndexIntersects | esriSpatialRelWithin

f

The response format. The default response format is html. The supportsQueryFormats layer property describes what formats are supported. Note that the default response format, html, is always supported.

Example

"supportedQueryFormats": "JSON,geoJSON,PBF"

The output format geoJSON is not supported if returnM is true. Starting at 10.8, geojson will return results that match the RFC7946 specification if no outSR is specified, or if outSR is set to 4326. Setting a different outSR value will return projected results. However, these will not match the RFC7946 specification.

Values: html | json | geojson | pbf

Date-time queries

If you are working with ArcGIS Server 10.4 or later, 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, Query always returns date values in UTC. You can set the dateFieldsTimezoneID property on the ArcMap Service Editor Parameters tab when you publish the service. If you don't have dateFieldsTimezoneID set, be sure your WHERE clause issues the time you are querying in UTC. The dateFieldsTimezoneID property does not apply to fields that were time enabled through the Layer Properties Time tab in ArcMap at the time of publishing.

At 10.6.1 and later, the INTERVAL syntax can be used in place of the date-time queries and will be standardized across all map and feature services. There are two specific ways to use the INTERVAL syntax.

For use with INTERVAL, there are two main formats for date and time stamp:

//Date
<DateField> >= CURRENT_DATE -+ INTERVAL '<IntervalValue>' <TimeStampFormat>

//Timestamp
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL '<IntervalValue>' <TimeStampFormat>

You aren't limited to DAY when using INTERVAL. Here are some of the other formats you can use:

NoteNote:

These query formats can be used with CURRENT_DATE in place of CURRENT_TIMESTAMP and can be used with + or - INTERVAL values. As of 10.6.1, CURRENT_TIMESTAMP will return the date and time in the time zone of the back-end geodatabase for ArcGIS Enterprise hosted feature services. This means that you may get inconsistent results when querying hosted feature services, as all values are stored in UTC.

//'DD' Day
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD' DAY

//'HH' Hour
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'HH' HOUR

//'MI' Minute
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'MI' MINUTE

//'SS(.FFF)' Second
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'SS(.FFF)' SECOND

//'DD HH' DAY TO HOUR
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD HH' DAY TO HOUR

//'DD HH:MI' DAY TO MINUTE
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD HH:MI' DTY TO MINUTE

//'DD HH:MI:SS(.FFF)' DAY TO SECOND
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'DD HH:MI:SS(.FFF)' DAY TO SECOND

//'HH:MI' HOUR TO MINUTE
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'HH:MI' HOUR TO MINUTE

//'HH:SS(.FFF)' HOUR TO SECOND
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'HH:SS(.FFF)' HOUR TO SECOND

//'MI:SS(.FFF)' MINUTE TO SECOND
<DateField> >= CURRENT_TIMESTAMP -+ INTERVAL 'MI:SS(.FFF)' MINUTE TO SECOND
NoteNote:

There are some additional considerations. Except for the second (.FFF) value, all values must be integers. If a date field is specified in the outFields list, the date-time will always be returned in formatted UTC.

Percentile statistic type

The percentile statisticType is supported if the supportsPercentileStatistics layer property (in advancedQueryCapabilities) is true. The percentile indicates the value below or above which a given percentage of values in a group of data values falls. For example, the ninetieth percentile (value 0.9) is the value below which 90 percent of the data values may be found. For percentile statistics, there are two statisticTypes, PERCENTILE_DISC (discrete) and PERCENTILE_CONT (continuous). Discrete returns a data value from within that dataset while continuous is an interpolated value.

The orderBy statistic parameter can also be used to calculate the percentile. For example, in a set of 10 values from 1 to 10, the percentile value for 0.9 with orderBy set as ascending (ASC) is 9, while the percentile for value 0.9 with orderBy set as descending (DESC) is 2. The default is ASC.

NoteNote:

Percentile statisticTypes cannot be used with the havingClause parameter.

Syntax

[
  {
    "statisticType": "<PERCENTILE_CONT | PERCENTILE_DISC>",
    "statisticParameters": {
      "value": percentile_value,
      "orderBy": "<ASC | DESC>"
    },
    "onStatisticField": "Field1", 
    "outStatisticFieldName": "Out_Field_Name1"
  },
  {
    "statisticType": "<PERCENTILE_CONT | PERCENTILE_DISC>",
    "statisticParameters": {
      "value": percentile_value,
      "orderBy": "<ASC | DESC>"
    },
    "onStatisticField": "Field2", 
    "outStatisticFieldName": "Out_Field_Name2"
  }
]

Example

[
  {
    "statisticType": "PERCENTILE_CONT",
    "statisticParameters": {
      "value": 0.9
    },
    "onStatisticField": "NEAR_DIST",
    "outStatisticFieldName": "pop90_cont"
  },
  {
    "statisticType": "PERCENTILE_DISC",
    "statisticParameters": {
      "value": 0.9,
      "orderBy": "DESC"
    },
    "onStatisticField": "population",
    "outStatisticFieldName": "pop90_desc"
  }
]

Quantization parameters JSON properties

Property

Description

extent

An extent defining the quantization grid bounds. Its spatialReference matches the input geometry spatial reference if one is specified for the query. Otherwise, the extent will be in the layer's spatial reference.

mode

Geometry coordinates are optimized for viewing and displaying of data. The view value specifies that geometry coordinates should be optimized for viewing and displaying of data. The edit value specifies that full-resolution geometries should be returned, which can support lossless editing.

NoteNote:

The edit value can only be used when the supportsQuantizationEditMode layer property is true.

Value: view | edit

originPosition

Integer coordinates will be returned relative to the origin position defined by this property value. The default value is upperLeft.

Values: upperLeft | lowerLeft

tolerance

The tolerance is the size of one pixel in the outSpatialReference units. This number is used to convert the coordinates to integers by building a grid with resolution matching the tolerance. Each coordinate is then snapped to one pixel on the grid. Consecutive coordinates snapped to the same pixel are removed to reduce the overall response size.

The units of tolerance are defined by outSpatialReference. If the outSpatialReference is not specified, tolerance is assumed to be in the unit of the spatial reference of the layer. If the tolerance is not specified, the maxAllowableOffset is used.

NoteNote:

If the tolerance and maxAllowableOffset are not specified, a default 10,000 by 10,000 grid is used.

If mode is set to edit, the tolerance is always set to the full-resolution tolerance of the spatial reference regardless of what is passed in or set for the maxAllowableOffset. If mode is set to view and the tolerance and maxAllowableOffset are not specified, a default 10,000 by 10,000 grid is used.

Return type and max record count

The maxTileRecordCount and maxStandardRecordCount are determined by the server and display in the layer metadata. The feature service assigns the maxRecordCount relevant to the value from the resultType parameter. If resultType is not included in the request, the default maxRecordCount is always used. This can be the default server-assigned value (1000, 2000) or an overwritten value provided by the service owner or admin. The values of the max record counts might vary based on the type of the data (polygon, point, polyline, table).

If the resultType is specified, but the resultRecordCount is not specified with the resultOffset, the server will determine the maxRecordCount relevant to the resultType query parameter. The client can supply the resultRecordCount parameter in the request. This cannot be greater than the standard/tile maxRecordCount value if resultType is used.

The layer metadata also includes maxRecordCountFactor that can be configured from the admin API. The server maxRecordCountFactor for the tileMaxRecordCount and standardMaxRecordCount is used as a multiplier for the server base value. All maxRecordCount values are adjusted with the maxRecordCountFactor.

Pagination query also supports the resultType query parameter.

SQL format

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

sqlFormat value

useStandardizedQuery is true

useStandardizedQuery is 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

Example one: WHERE clause

Example two: WHERE clause | OBJECTIDs only

Example three: WHERE clause | DAY

Example four: WHERE clause | DAY TO HOUR

Example five: resultOffset | resultRecordCount

Example six: resultType=none

Example seven: resultType=standard

Example eight: resultType=tile

Example one

Query using a WHERE clause:

https://machine.domain.com/webadaptor/rest/services/Earthquakes/EarthquakesFromLastSevenDays/FeatureServer/0/query?where=magnitude+%3E+4.5&outFields=*&returnGeometry=true&returnIdsOnly=false&f=html

Example two

Query a table using a WHERE clause and return OBJECTIDs only:

https://machine.domain.com/webadaptor/rest/services/SanFrancisco/311Incidents/FeatureServer/1/query?where=agree_with_incident+%3D+1&returnGeometry=true&returnIdsOnly=true&f=html

Example three

Query using a WHERE clause using the DAY format:

https://machine.domain.com/webadaptor/rest/services/DateTimeIntervalQuery/FeatureServer/0/query?
where=date_time > CURRENT_TIMESTAMP - INTERVAL '1' DAY&returnGeometry=false&returnCountOnly=true&resultType=&f=pjson

Example four

Query using a WHERE clause using the DAY TO HOUR format:

https://machine.domain.com/webadaptor/rest/services/DateTimeIntervalQuery/FeatureServer/0/query?
where=date_time > CURRENT_TIMESTAMP + INTERVAL '1 04' DAY TO HOUR&returnGeometry=false&returnCountOnly=true&resultType=&f=pjson

Example five

Page through a query result using resultOffset and resultRecordCount to get the next set of results. Requesting to skip the first 5 records and return the next 10 counties in California ordered by population:

https://machine.domain.com/webadaptor/rest/services/USA/MapServer/3/query?where=STATE_NAME='California'&outFields=Name,Population&returnGeometry=false&resultOffset=5&resultRecordCount=10&orderByFields=Population&f=pjson

Example six

When resultType is set to none. The default maxRecordCount is always used. This can be the default server assigned ("maxRecordCount" : 2000) or an overwritten value by the service owner/admin.

https://machine.domain.com/webadaptor/rest/services/USAStatesRiversCapitals/FeatureServer/2/query?where=1=1&objectIds=&time=&geometry=&geometryType=esriGeometryEnvelope&inSR=&spatialRel=esriSpatialRelIntersects&resultType=none&distance=&units=esriSRUnit_Meter&outFields=*&returnGeometry=true&multipatchOption=&maxAllowableOffset=&geometryPrecision=&outSR=&returnIdsOnly=false&returnCountOnly=false&returnExtentOnly=false&returnDistinctValues=false&orderByFields=&groupByFieldsForStatistics=&outStatistics=&resultOffset=&resultRecordCount=&returnZ=false&returnM=false&quantizationParameters=&sqlFormat=none&f=html&token

Example seven

When resultType is set to standard. The standardMaxRecordCount is always used, for example, "standardMaxRecordCount" : 32000 for point and table layers.

https://machine.domain.com/webadaptor/rest/services/USAStatesRiversCapitals/FeatureServer/2/query?where=1=1&objectIds=&time=&geometry=&geometryType=esriGeometryEnvelope&inSR=&spatialRel=esriSpatialRelIntersects&resultType=standard&distance=&units=esriSRUnit_Meter&outFields=*&returnGeometry=true&multipatchOption=&maxAllowableOffset=&geometryPrecision=&outSR=&returnIdsOnly=false&returnCountOnly=false&returnExtentOnly=false&returnDistinctValues=false&orderByFields=&groupByFieldsForStatistics=&outStatistics=&resultOffset=&resultRecordCount=&returnZ=false&returnM=false&quantizationParameters=&sqlFormat=none&f=html&token=

Example eight

When resultType is set to tile. The tileMaxRecordCount is always used, for example, "tileMaxRecordCount" : 8000 for point layers.

https://machine.domain.com/webadaptor/rest/services/USAStatesRiversCapitals/FeatureServer/2/query?where=1=1&objectIds=&time=&geometry=&geometryType=esriGeometryEnvelope&inSR=&spatialRel=esriSpatialRelIntersects&resultType=tile&distance=&units=esriSRUnit_Meter&outFields=*&returnGeometry=true&multipatchOption=&maxAllowableOffset=&geometryPrecision=&outSR=&returnIdsOnly=false&returnCountOnly=false&returnExtentOnly=false&returnDistinctValues=false&orderByFields=&groupByFieldsForStatistics=&outStatistics=&resultOffset=&resultRecordCount=&returnZ=false&returnM=false&quantizationParameters=&sqlFormat=none&f=html&token=

JSON Response syntax

Example one

When returnIdsOnly is set to false and returnCountOnly is set to false:

{
  "objectIdFieldName": "<objectIdFieldName>",
  "globalIdFieldName": "<globalIdFieldName>",
  "geometryType": "<geometryType>", //for feature layers only
  "spatialReference": <spatialReference>, //for feature layers only
  "hasZ": <true|false>, //added in 10.1
  "hasM": <true|false>, //added in 10.1
  "fields": [
    {"name": "<fieldName1>", "type" : "<fieldType1>", "alias" : "<fieldAlias1>", "length" : "<length1>"},
    {"name": "<fieldName2>", "type" : "<fieldType2>", "alias" : "<fieldAlias2>", "length" : "<length2>"}
  ],
  "features": [ //features will include geometry for feature layers only
    <feature1>, <feature2> 
  ]
}

Example two

When returnCountOnly is set to true:

{
  "count": <count>
}

Example three

When returnCountOnly is set to true and returnExtentOnly is set to true:

{
  "count": <count>, 
  "extent": <envelope>
}

Example four

When returnIdsOnly is set to true:

{
  "objectIdFieldName": "<objectIdFieldName>",
  "objectIds": [ <objectId1>, <objectId2> ]
}

JSON Response example

Example one: returnIdsOnly=false | returnCountOnly=false

Example two: returnIdsOnly=false | returnCountOnly=false | outFields=""

Example three: returnIdsOnly=false | returnCountOnly=false | outFields="" | geometryPrecision=3

Example four: returnIdsOnly=true

Example five: returnCountOnly=true

Example six: returnGeometry=true | returnCentroid=true

Example seven: returnGeometry=false | returnCentroid=true

Example one

When returnIdsOnly is set to false and returnCountOnly is set to false:

{
  "objectIdFieldName": "objectid",
  "globalIdFieldName": "",
  "geometryType": "esriGeometryPoint",
  "spatialReference": {
    "wkid": 4326
  },
    "fields": [
    {
      "name": "objectid", 
      "type": "esriFieldTypeOID", 
      "alias": "Object ID"
    }, 
    {
      "name": "datetime", 
      "type": "esriFieldTypeDate", 
      "alias": "Earthquake Date",
      "length": 36
    }, 
    {
      "name": "depth", 
      "type": "esriFieldTypeDouble", 
      "alias": "Depth"
    }, 
    {
      "name": "eqid", 
      "type": "esriFieldTypeString", 
      "alias": "Earthquake ID",
      "length": 50
    }, 
    {
      "name": "latitude", 
      "type": "esriFieldTypeDouble", 
      "alias": "Latitude"
    }, 
    {
      "name": "longitude", 
      "type": "esriFieldTypeDouble", 
      "alias": "Longitude"
    }, 
    {
      "name": "magnitude", 
      "type": "esriFieldTypeDouble", 
      "alias": "Magnitude"
    }, 
    {
      "name": "numstations", 
      "type": "esriFieldTypeInteger", 
      "alias": "Number of Stations"
    }, 
    {
      "name": "region", 
      "type": "esriFieldTypeString", 
      "alias": "Region", 
      "length": 200
    }, 
    {
      "name": "source", 
      "type": "esriFieldTypeString", 
      "alias": "Source", 
      "length": 50
    }, 
    {
      "name": "version", 
      "type": "esriFieldTypeString", 
      "alias": "Version",
      "length": 50
    }
  ],
  "features": [
    {
      "geometry": {
        "x": -178.24479999999991,
        "y": 50.012500000000045
      },
      "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.865099999999927,
        "y": -37.486599999999953
      },
      "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"
      }
    }
  ]
}

Example two

When returnIdsOnly is set to false, returnCountOnly is set to false, and outFields is not specified:

{
  "objectIdFieldName": "objectid",
  "globalIdFieldName": "",
  "geometryType": "esriGeometryPoint",
  "spatialReference": {
    "wkid": 4326
  },
  "fields": [],
  "features": [
    {
      "geometry": {
        "x": 237.17180000000008,
        "y": 38.844700000000046
      },
      "attributes": {}
    },
    {
      "geometry": {
        "x": 242.89430000000004,
        "y": 34.559200000000089
      },
      "attributes": {}
    }
  ]
}

Example three

When returnIdsOnly is set to false, returnCountOnly is set to false, outFields is not specified, and geometryPrecision is set to 3:

{
  "objectIdFieldName": "objectid",
  "globalIdFieldName": "",
  "geometryType": "esriGeometryPoint",
  "spatialReference": {
    "wkid": 4326
  },
  "fields": [],
  "features": [
    {
      "geometry": {
        "x": 237.172,
        "y": 38.845
      },
      "attributes": {}
    },
    {
      "geometry": {
        "x": 242.894,
        "y": 34.559
      },
      "attributes": {}
    }
  ]
}

Example four

When returnIdsOnly is set to true:

{
  "objectIdFieldName": "objectid", 
  "objectIds": [1, 2, 3, 4, 5, 7]
}

Example five

When returnCountOnly is set to true:

{
  "count": 48
}

Example six

When returnGeometry is set to true and returnCentroid is set to true:

{
  "geometryType": "esriGeometryPolygon", 
  "features": [
    {
      "attributes": {"FID" : 6,}, 
      "geometry": {
        "rings": [
          [
            [3665984.6341781, 4199764.97834117], 
            [3607400.16786144, 4129939.04834019], 
            [3593238.34218707, 4176854.4199198], 
            [3665984.6341781, 4199764.97834117]
          ]
        ]
      }, 
      "centroid": {
        "x": 3702339.9805305949, 
        "y": 4174890.1188574196
      }
    }
  ]
}

Example seven

When returnGeometry is set to false and returnCentroid is set to true:

{
  "geometryType": "esriGeometryPolygon", 
  "features": [
    {
      "attributes" : {
        "FID" : 6, 
      }, 
      "centroid" : {
        "x" : 3702339.9805305949, 
        "y" : 4174890.1188574196
      }
    }
  ]
}