Query (Image Service)

URL:: https://<imageservice-url>/query
Methods:: GET
Required Capability:: Catalog
Version Introduced:: 10.0

Description

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

While there is a limit (maxRecordCount) 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 use 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.8.1, the query operation supports rasterQuery if the image service uses ArcObjects11 or ArcObjectsRasterRendering as the service provider.

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

Request parameters

Parameter	Details
`f`	The response format. The default response format is `html` . Values: `html` \| `json`
`objectIds`	The object IDs of the raster catalog to be queried. Syntax Use dark colors for code blocksCopy `1 objectIds=<objectId1>, <objectId2>` Example Use dark colors for code blocksCopy `1 objectIds=37, 462`
`where`	A where clause for the query filter. Any legal SQL where clause operating on the fields in the raster catalog is allowed. Example Use dark colors for code blocksCopy `1 where=POP2000 > 350000`
`time`	The time instant or the time extent to query. Use dark colors for code blocksCopy `1 2 3 4 5 6 7 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`	The geometry that will be applied 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 comma-separated syntax. Syntax Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 //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 Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 //Envelope example 1 geometryType=esriGeometryEnvelope&geometry={xmin: -104, ymin: 35.6, xmax: -94.32, ymax: 41} //Envelope example 2 geometryType=esriGeometryEnvelope&geometry=-104,35.6,-94.32,41 //Point example geometryType=esriGeometryPoint&geometry=-104,35.6`
`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). Example Use dark colors for code blocksCopy `1 geometryPrecision=3`
`geometryType`	Specifies the type of geometry provided in the `geometry` parameter. The geometry type can be envelope, point, line, or polygon. The default geometry type is envelope (`esriGeometryEnvelope` ). Values: `esriGeometryPoint` \| `esriGeometryMultipoint` \| `esriGeometryPolyline` \| `esriGeometryPolygon` \| `esriGeometryEnvelope`
`inSR`	The spatial reference of the input `geometry` value. The spatial reference can be specified as either a well-known ID or as a spatial reference JSON object. If no value is provided, the `geometry` value is assumed to be in the spatial reference of the service.
`spatialRel`	Specifies the spatial relationship that will 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`
`outFields`	The list of fields that will 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 will include all the field values. The wildcard also implies `returnGeometry` is `true`, so setting `returnGeometry` to `false` will have no effect. Example Use dark colors for code blocksCopy `1 2 3 4 5 //Comma-delimited list example outFields=AREANAME,ST,POP2000 //Wildcard example outFields=`
`returnGeometry`	Specifies whether the result set will include the geometry associated with each result (`true` ). The default is `true`. If the `outFields` parameter is set to the wildcard "*", it implies `returnGeometry` is `true`, so setting `returnGeometry` to `false` will have no effect. Values: `true` \| `false`
`outSR`	The spatial reference of the returned geometry.
`returnIdsOnly`	Specifies whether the response will only include an array of raster IDs (`true`). When `false`, the response will be 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 use this to get all the query conforming raster IDs by specifying `returnIdsOnly` as `true` and subsequently requesting raster sets for subsets of raster IDs. Values: `true` \| `false`
`returnCountOnly`	Specifies whether the response will only include the `count` value (number of features) that would be returned by a query (`true`). When `false` , the response will be a feature set. The default is `false` . This parameter supersedes the `returnIdsOnly` parameter. Values: `true` \| `false`
`pixelSize`	The pixel size that will be used to query visible rasters. If no value is provided, 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 comma-separated syntax. Syntax Use dark colors for code blocksCopy `1 2 3 4 5 //JSON structure pixelSize={point} //Point simple syntax pixelSize=<x>,<y>` Examples Use dark colors for code blocksCopy `1 2 3 4 5 //Example one pixelSize={"x": 0.18, "y": 0.18} //Example two pixelSize=0.18,0.18`
`orderByFields`	Order results by one or more field names. This parameter uses `ASC` or `DESC` for ascending or descending order, respectively. The parameter defaults to `ASC` if no order is provided. This parameter is only supported if the `supportsAdvancedQueries` property of the image service is `true` . Syntax Use dark colors for code blocksCopy `1 2 orderByFields=field1 <ORDER>, field2 <ORDER>, field3 <ORDER>` Example Use dark colors for code blocksCopy `1 orderByFields=SensorName ASC, ProductName DESC`
`returnDistinctValues`	Specifies whether distinct values based on the fields specified in the `outFields` parameter will be returned (`true`). This parameter applies only if the `supportsAdvancedQueries` property of the image service is `true`. Values: `true` \| `false`
`outStatistics`	An array of statistic definitions for one or more field-based statistics to be calculated. The definitions specify the type of statistic, the field on which it is to be calculated, and the resulting output field name. This parameter is only supported if the `supportsStatistics` property on the image service is `true` . This parameter takes precedence over the `returnCountOnly`, `returnIdsOnly`, and `returnGeometry` parameters. If `outStatistics` is used, the only other parameters that will be used are `groupByFieldsForStatistics`, `orderByFields`, `pixelSize`, `time`, `geometry`, and `where`. Note If `outStatisticFieldName` is empty or missing, the image server assigns a field name to the returned statistic field. A valid field name can only contain alphanumeric characters and an underscore. Syntax Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 [ { "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 Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 [ { "statisticType": "max", "onStatisticField": "acquisitionDate", "outStatisticFieldName": "LatestImageDate" }, { "statisticType": "min", "onStatisticField": "LowPS", "outStatisticFieldName": "BestSpatialResolution" } ]`
`groupByFieldsForStatistics`	One or more field names using the values that need to be grouped for calculating the statistics. This parameter is only valid when the `outStatistics` parameter is used. Syntax Use dark colors for code blocksCopy `1 groupByFieldsForStatistics=field1, field2` Example Use dark colors for code blocksCopy `1 groupByFieldsForStatistics=SensorName, ProductName`
`multidimensionalDefinition`	The filters defined by multiple dimensional definitions. See Dimensional Definition objects for more information. Syntax Use dark colors for code blocksCopy `1 multidimensionalDefinition=[dimensionalDefinition1, dimensionalDefinition2, ...]`
`resultOffset`	The number of records that will be skipped when fetching query results. The query results start from the next record (for example, `resultOffset` + 1). The default value is 0. This parameter only applies when `supportsPagination` is `true`. You can use this parameter to fetch records that are beyond the `maxRecordCount` value. For example, if `maxRecordCount` is `1000`, you can get the next 100 records by setting `resultOffset` to `1000` and `resultRecordCount` to `100`. Query results can return the results in the range of 1001 to 1100.
`resultRecordCount`	The number of query results that will be fetched. When the `resultOffset` value is provided and this parameter value is not, the image service defaults to the `maxRecordCount` value. The maximum value for this parameter is the value of the layer's `maxRecordCount` property. This parameter only applies when `supportsPagination` is `true`. Example Use dark colors for code blocksCopy `1 2 //Fetches up to 10 records resultRecordCount=10`
`maxAllowableOffset`	The maximum offset that will be used for generalizing geometries returned by the query operation. This parameter value will be in the units of the `outSR` value. If no `outSR` value is provided, the `maxAllowableOffset` value is assumed to be in the unit of the spatial reference of the service. Example Use dark colors for code blocksCopy `1 maxAllowableOffset=2`
`returnTrueCurves`	Specifies whether true curves will be returned in the output geometries (`true`). When `false`, curves will be converted to densified polylines or polygons. Values: `true` \| `false`
`rasterQuery`	Introduced at 10.8.1. A query based on key properties of each raster catalog item. Any legal SQL where clause operating on the key properties of raster catalog items is allowed. Example Use dark colors for code blocksCopy `1 rasterQuery=LANDSAT_WRS_PATH >= 150 AND LANDSAT_WRS_PATH<= 165`

Example usage

Example 1

The following is a sample request URL for the query operation that demonstrates a query that uses a where clauses and requests to return specific outfields:

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

The following is a sample request URL for the query operation that demonstrates a query that uses point geometry and where clauses and requests to return only object IDs:

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

The following is a sample request URL for the query operation that demonstrates querying distinct sensors and products in an image service:

Use dark colors for code blocksCopy
https://machine.domain.com/webadaptor/rest/services/myImageService/ImageServer/query?where=1=1&outFields=SensorName,ProductName&returnDistinctValuesOnly=true&orderByFields=SensorName ASC, ProductName DESC&f=pjson

Example 4

The following is a sample request URL for the query operation that demonstrates querying for the latest image acquisition date for each sensor:

Use dark colors for code blocksCopy
https://machine.domain.com/webadaptor/rest/services/myImageService/ImageServer/query?outStatistics=[{"statisticType": "max","onStatisticField": "acquisitionDate","outStatisticFieldName": "LatestImageDate"}]&groupByFieldsForStatistics=SensorName&f=pjson

JSON Response syntax examples

Example 1

The following JSON syntax example demonstrates the response returned when the request includes returnIdsOnly as false and returnCountOnly as false:

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

Example 2

The following JSON syntax example demonstrates the response returned when the request includes returnCountOnly as true:

Use dark colors for code blocksCopy
{
  "count": <count>
}

Example 3

The following JSON syntax example demonstrates the response returned when the request includes returnIdsOnly as true:

Use dark colors for code blocksCopy
{
  "objectIdFieldName": "<objectIdFieldName>",
  "objectIds": [
    <objectId1>,
    <objectId2>
  ]
}

JSON Response examples

Example 1

The following is a sample response example for the query operation:

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

Example 2

The following is a sample response example for the query operation when returnCountOnly is true:

Use dark colors for code blocksCopy
{
  "count":48
}