Query (Image Service)

Description

The query operation is performed on an image service resource. It queries by applying the filter specified by the user. The result of this operation is either a set of features or an array of raster IDs (if returnIdsOnly is set to true), count (if returnCountOnly is set to true), or a set of field statistics (if outStatistics is used).

While there is a limit (maxRecordCount) on the number of features included in the feature set response, there is no limit on 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.

At 10.4, the query operation supports geometryPrecision, maxAllowableOffset and returnTrueCurves.

At 10.3.1, the query operation supports resultOffset and resultRecordCount.

At 10.3, the query operation supports multidimensionalDefinition.

At 10.2.1, the query operation supports outStatistics, groupByFieldsForStatistics, orderByFields, and returnDistinctValues.

You can provide arguments to the query operation as query parameters defined in the following parameters table:

Request parameters

Parameter

Details

f

Description: The response format. The default response format is html.

Values: html | json

objectIds

Description: The object IDs of this raster catalog to be queried.

When this parameter is specified, any other filter parameters (including where) are ignored.

When this parameter is specified, setting returnIdsOnly=true is invalid.

Syntax: objectIds=<objectId1>, <objectId2>

Example: objectIds=37, 462

where

Description: A where clause for the query filter. Any legal SQL where clause operating on the fields in the raster catalog is allowed.

Example: where=POP2000 > 350000

time

Description: The time instant or the time extent to query.

Time instant

Syntax: time=<timeInstant>

Example: time=1199145600000 (1 Jan 2008 00:00:00 GMT)

Time extent (For time extents, one of <startTime> or <endTime> could be 'null').

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 startTime, or endTime will represent infinity for start or end time, respectively.

geometry

Description: The geometry to apply as the spatial filter. The structure of the geometry is the same as the structure of the JSON geometry objects returned by the ArcGIS REST API. In addition to the JSON structures, for envelopes and points, you can specify the geometry with a simpler comma-separated syntax.

Syntax:

  • JSON structures: geometryType=<geometryType>&geometry={geometry}
  • Envelope simple syntax: geometryType=esriGeometryEnvelope&geometry=<xmin>,<ymin>,<xmax>,<ymax>
  • Point simple syntax: geometryType=esriGeometryPoint&geometry=<x>,<y>

Examples:

  • geometryType=esriGeometryEnvelope&geometry={xmin: -104, ymin: 35.6, xmax: -94.32, ymax: 41}
  • geometryType=esriGeometryEnvelope&geometry=-104,35.6,-94.32,41
  • geometryType=esriGeometryPoint&geometry=-104,35.6

geometryPrecision

This option was added at 10.4.

Description: This option can be used to specify the number of decimal places in the response geometries returned by the query operation. This applies to X and Y values only (not m- or z-values).

Example: geometryPrecision=3

geometryType

Description: The type of geometry specified by the geometry parameter. The geometry type can be an envelope, point, line, or polygon. The default geometry type is an envelope.

Values: esriGeometryPoint | esriGeometryMultipoint | esriGeometryPolyline | esriGeometryPolygon | esriGeometryEnvelope

inSR

Description: The spatial reference of the input geometry.

The spatial reference can be specified as either a well-known ID or as a spatial reference JSON object.

If inSR is not specified, the geometry is assumed to be in the spatial reference of the service.

spatialRel

Description: The spatial relationship to be applied on the input geometry while performing the query. The supported spatial relationships include intersects, contains, envelope intersects, within, and so on. The default spatial relationship is intersects (esriSpatialRelIntersects).

Values: esriSpatialRelIntersects | esriSpatialRelContains | esriSpatialRelCrosses | esriSpatialRelEnvelopeIntersects | esriSpatialRelIndexIntersects | esriSpatialRelOverlaps | esriSpatialRelTouches | esriSpatialRelWithin

outFields

Description: The list of fields to be included in the returned result set. This list is a comma-delimited list of field names. To request geometry, set returnGeometry to true.

You can also specify the wildcard "*" as the value of this parameter. In this case, the query results include all the field values. The wildcard also implies returnGeometry=true; therefore, setting returnGeometry to false will have no effect.

Example: outFields=AREANAME,ST,POP2000

Example (wildcard usage): outFields=*

returnGeometry

Description: If true, the result set includes the geometry associated with each result. The default is true.

If the outFields parameter is set to the wildcard "*", it implies returnGeometry=true; therefore, setting returnGeometry to false has no effect.

Values: true | false

outSR

Description: The spatial reference of the returned geometry.

The spatial reference can be specified as either a well-known ID or as a spatial spatial reference JSON object.

If outSR is not specified, the geometry is returned in the spatial reference of the image service.

returnIdsOnly

Description: If true, the response only includes an array of raster IDs. Otherwise, the response is a raster set. The default is false.

While there is a limit to the number of rasters included in the raster set response, there is no limit to the number of raster IDs returned in the ID array response. Clients can exploit this to get all the query conforming raster IDs by specifying returnIdsOnly=true and subsequently requesting raster sets for subsets of raster IDs.

Values: false | true

returnCountOnly

This option was added at 10.0 SP1.

Description: If true, the response only includes the count (number of features) that would be returned by a query. Otherwise, the response is a feature set. The default is false. This option supersedes the returnIdsOnly parameter.

Values: false | true

pixelSize

This option was added at 10.1 SP1.

Description: Query visible rasters at a given pixel size. If pixelSize is not specified, rasters at all resolutions can be queried.

The structure of the pixelSize parameter is the same as the structure of the point object returned by the ArcGIS REST API. In addition to the JSON structure, you can specify the pixel size with a simpler comma-separated syntax.

Syntax:

  • JSON structure: pixelSize={point}
  • Point simple syntax: pixelSize=<x>,<y>

Examples:

  • pixelSize={"x": 0.18, "y": 0.18}
  • pixelSize=0.18,0.18

orderByFields

This option was added at 10.2.1.

Description: Order results by one or more field names. Use ASC or DESC for ascending or descending order, respectively.

NoteNote:

  • orderByFields is supported only if the supportsAdvancedQueries property of the image service is true.
  • orderByFields defaults to ASC (ascending order) if <ORDER> is unspecified.

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

Example: orderByFields=SensorName ASC, ProductName DESC

returnDistinctValues

This option was added at 10.2.1.

Description: If true, returns distinct values based on the fields specified in outFields. This parameter applies only if the supportsAdvancedQueries property of the image service is true.

Syntax: returnDistinctValues=<true | false>

Example: returnDistinctValues=true

outStatistics

This option was added at 10.2.1.

Description: The definitions for one or more field-based statistics to be calculated.

NoteNote:

  • outStatistics is supported only if the suppportsStatistics property of the image service is true.
  • If outStatisticFieldName is empty or missing, the image server would assign a field name to the returned statistic field. A valid field name can only contain alphanumeric characters and an underscore.
  • outStatistics takes precedence over returnCountOnly, returnIdsOnly, and returnGeometry. The only other parameters that will be used are groupByFieldsForStatistics, orderByFields, pixelSize, time, geometry, and where.

Values: An array of statistic definitions. A statistic definition specifies the type of statistic, the field on which it is to be calculated, and the resulting output field name.

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": "max",
    "onStatisticField": "acquisitionDate",
    "outStatisticFieldName": "LatestImageDate"
  },
  {
    "statisticType": "min",
    "onStatisticField": "LowPS",
    "outStatisticFieldName": "BestSpatialResolution"
  }
]

groupByFieldsForStatistics

This parameter was added at 10.2.1.

Description: One or more field names using the values that need to be grouped for calculating the statistics.

NoteNote:

groupByFieldsForStatistics is valid only when the outStatistics parameter is used.

Syntax: groupByFieldsForStatistics=field1, field2

Example: groupByFieldsForStatistics=SensorName, ProductName

multidimensionalDefinition

This parameter was added at 10.3. See Dimensional Definition objects for more information.

Description: The filters defined by multiple dimensional definitions.

Syntax: [dimensionalDefinition1, dimensionalDefinition2, ...]

resultOffset

This parameter was added at 10.3.1.

Description: This option fetches query results by skipping a specified number of records. The query results start from the next record (i.e., resultOffset + 1). The Default value is 0.

This parameter only applies when supportsPagination is true.

You can use this option to fetch records that are beyond maxRecordCount.

For example, if maxRecordCount is 1000, you can get the next 100 records by setting resultOffset = 1000 and resultRecordCount = 100, query results can return the results in the range of 1001 to 1100.

resultRecordCount

This parameter was added at 10.3.1.

Description: This option fetches query results up to the resultRecordCount specified. When resultOffset is specified and this parameter is not, image service defaults to maxRecordCount. The maximum value for this parameter is the value of the layer's maxRecordCount property.

This parameter only applies if supportsPagination is true.

Example: resultRecordCount=10 to fetch up to 10 records

maxAllowableOffset

This option was added at 10.4.

Description: This option can be used to specify the maxAllowableOffset to be used for generalizing geometries returned by the query operation.

The maxAllowableOffset is in the units of the outSR. If outSR is not specified, maxAllowableOffset is assumed to be in the unit of the spatial reference of the service.

Example: maxAllowableOffset=2

returnTrueCurves

This option was added at 10.4.

Description: If true, returns true curves in output geometres, otherwise curves get converted to densified polylines or polygons.

Syntax: returnTrueCurves=<true | false>

Example: returnTrueCurves=true

Example usage

Example 1: Query using a where clause and return specific outfields.

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Portland/CascadeLandsat/ImageServer/query?where=Name LIKE 'p045r028%' AND Name NOT LIKE 'Ovr%'&outFields=Name,MinPS,MaxPS,LowPS,HighPS&returnGeometry=true&returnIdsOnly=false&f=html

Example 2: Query using a point geometry and a where clause. Returns only OBJECTIDs.

http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Portland/CascadeLandsat/ImageServer/query?where=NAME NOT LIKE 'Ov_%'&geometry={"x":-122.895114,"y":45.558214,"spatialReference":{"wkid":4269}}&geometryType=esriGeometryPoint&inSR=4326&spatialRel=esriSpatialRelIntersects&outFields=*&returnGeometry=false&returnIdsOnly=true&f=html

Example 3: Query distinct sensors and products in an image service.

http://myserver/arcgis/rest/services/myImageService/ImageServer/query?where=1=1&outFields=SensorName,ProductName&returnDistinctValuesOnly=true&orderByFields=SensorName ASC, ProductName DESC

Example 4: Query latest image acquisition date for each sensor.

http://myserver/arcgis/rest/services/myImageService/ImageServer/query?outStatistics=[{ "statisticType": "max", "onStatisticField": "acquisitionDate", "outStatisticFieldName": "LatestImageDate" }]&groupByFieldsForStatistics=SensorName

JSON response syntax (when returnIdsOnly=false and returnCountOnly=false)

{
"objectIdFieldName" : "<objectIdFieldName>",
"spatialReference" : <spatialReference>,
"fields" : [
    {"name" : "<fieldName1>", "type" : "<fieldType1>", "alias" : "<fieldAlias1>", "length" : "<length1>"},
    {"name" : "<fieldName2>", "type" : "<fieldType2>", "alias" : "<fieldAlias2>", "length" : "<length2>"}
],
"features" : [ 
  <feature1>, <feature2>
]
}

JSON response syntax (when returnCountOnly=true)

{
"count" : <count>
}

JSON response syntax (when returnIdsOnly=true)

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

JSON response example

{
"objectIdFieldName" : "IMAGEID",
"spatialReference" : {"wkid" : 4326},
"fields" : [{    "name" : "ST",    "alias" : "ST",    "type" : "esriFieldTypeString",    "length" : 2},
{
    "name" : "OBJECTID",    "alias" : "OBJECTID",    "type" : "esriFieldTypeOID"},
{    "name" : "AREANAME",    "alias" : "City Name",    "type" : "esriFieldTypeString",    "length" : 255}],
"geometryType" : "esriGeometryPolygon",
"features" : [
  {
    "geometry" : {
      "rings" : [ 
         [ [-97.06138,32.837], [-97.06133,32.836], [-97.06124,32.834], [-97.06127,32.832], [-97.06138,32.837] ]
      ]
    },
    "attributes" : {
      "IMAGEID" : 37,
      "OWNER" : "Joe Smith",
      "VALUE" : 94820.37,
      "APPROVED" : true,
      "LASTUPDATE" : 1227663551096
    }
  },
  {
    "geometry" : {
      "rings" : [ 
         [ [-97.06326,32.759], [-97.06298,32.755], [-97.06153,32.749], [-97.06326,32.759] ]
      ]
    },
    "attributes" : {
      "IMAGEID" : 462,
      "OWNER" : "John Doe",
      "VALUE" : 17325.90,
      "APPROVED" : false,
      "LASTUPDATE" : 1227628579430
    }
  }
]
}

JSON response example (when returnCountOnly=true)

{
"count":48
}