Query Top Features (Feature Service/Layer)

URL:: https://<root>/<serviceName>/FeatureServer/<layerId>/queryTopFeatures
Methods:: GET
Required Capability:: Query
Version Introduced:: 10.7

Description

The queryTopFeatures operation is performed on a feature service layer resource. This operation returns a feature set based on the top features by order within a group. For example, when querying counties in the United States, you want to return the top five counties by population in each state. To do this, you can use queryTopFeatures to group by state name, order by descending population, and return the first five rows from each group (state).

The topFilter parameter is used to set the group by, order by, and count criteria used in generating the result. The operation also has many of the same parameters (for example, where and geometry ) as the layer query operation. However, unlike the layer query operation, queryTopFeatures does not support parameters such as outStatistics and its related parameters or returnDistinctValues . Consult the advancedQueryCapabilities layer property for more details.

If the feature service supports the queryTopFeatures operation, it will include supportsTopFeaturesQuery as true in the advancedQueryCapabilities layer property.

Note

In ArcGIS Enterprise, there is no link from the REST services directory layer page to the queryTopFeatures HTML page. For layers with supportsTopFeaturesQuery as true in their metadata, you can access the queryTopFeatures HTML page using the following format:

Use dark colors for code blocksCopy
https://organization.example.com/<context>/rest/services/<serviceName>/FeatureServer/<layerId>/queryTopFeatures

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. For more information, see Query (Feature Service/Layer).
`objectIds`	The object IDs of the layer or table to be queried. Syntax Use dark colors for code blocksCopy `1 objectIds=<objectId1,objectId2>` Example Use dark colors for code blocksCopy `1 objectIds=42,93`
`time`	The time instant or the time extent to query. Note This parameter is only supported if the feature layer JSON information contains the `timeInfo` property. The `timeInfo` property can either be added to a feature layer using the Add to Definition (Feature Layer) operation or by setting the time properties on data in ArcGIS Pro. For an example of the `timeInfo` property, see Layer (Feature Service). Syntax Use dark colors for code blocksCopy `1 2 3 4 5 //Time instant time=<timeInstant> //Time extent time=<startTime>, <endTime>` Example Use dark colors for code blocksCopy `1 2 3 4 5 //Time instant (1 Jan 2008 00:00:00 GMT) time=1199145600000 //Time extent (1 Jan 2008 00:00:00 GMT to 1 Jan 2008 00:00:00 GMT) time=1199145600000, 1230768000000` A null value specified for start time or end time will represent infinity for start or end time, respectively. Example Use dark colors for code blocksCopy `1 time=null, 1230768000000`
`topFilter`	The JSON parameters that define the aggregation of the data. `groupByFields` defines the field or fields used to aggregate the data. `topCount` defines the number of features returned from the top features query and is a numeric value. `orderByFields` defines the order in which the top features will be returned. `orderByFields` can be specified in either ascending (`asc` ) or descending (`desc` ) order. The default is ascending. Syntax Use dark colors for code blocksCopy `1 2 3 4 5 { "groupByFields": <"field1, field2, ..., <fieldN">, "topCount": <topCount>, "orderByFields": <"field1"> }` Example Use dark colors for code blocksCopy `1 2 3 4 5 { "groupByFields": "worker", "topCount": 1, "orderByFields": "employeeNumber" }`
`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 Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 //JSON structures geometryType=<geometryType>&geometry={geometry} //Envelope 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 //JSON structure example geometryType=esriGeometryEnvelope&geometry=-104,35.6,-94.32,41 //Envelope example geometryType=esriGeometryEnvelope&geometry={xmin: -104, ymin: 35.6, xmax: -94.32, ymax: 41} //Point simple example 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` parameter 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`
`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 Use dark colors for code blocksCopy `1 distance=<distance>` Example Use dark colors for code blocksCopy `1 distance=100`
`units`	The unit for calculating the buffer distance. If `units` is not specified, the unit is derived from the geometry spatial reference. If the geometry spatial reference is not specified, the unit is derived from the feature service data spatial reference. 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 Use dark colors for code blocksCopy `1 2 3 4 5 //General example outFields=NAME,ST,AREA //Wildcard example outFields=`
`returnGeometry`	If `true` , the result includes the geometry associated with each feature returned. The default is `true` . Values: `true` \| `false`
`maxAllowableOffset`	The maximum allowable offset 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 Use dark colors for code blocksCopy `1 maxAllowableOffset=2`
`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`
`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.
`returnIdsOnly`	If `true` , the response only includes an array of object IDs. 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. When `objectIds` are specified, setting this parameter to `true` is invalid. Values: `true` \| `false`
`returnCountOnly`	If `true` , the response only includes the `count` (number of features or 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` is set to `true` , the response will return both the count and the extent. Values: `true` \| `false`
`returnExtentOnly`	If `true` , the response only includes the extent of the features that would be returned by the query. The default is `false` . If `returnCountOnly` is set to `true` , the response will return both the count and the extent. This parameter applies only if the `supportsReturningQueryExtent` property of the layer is `true` . Values: `true` \| `false` Note 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.
`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` .
`resultType` (Optional)	The `resultType` parameter can be used to control the number of features returned by the query operation. Support for the `resultType` parameter is advertised on the layer resource's metadata (`supportQueryWithResultType` as true). The tile value is used when the client is using a virtual tiling scheme when querying features. A virtual tiling scheme works similar to tiles in a tile map service layer. The standard value is used with a nontiled query in which the client will send only one query for the full extent. For more information, see the Considerations for `resultType` section below. Values: `none` \| `standard` \| `tile` Note Pagination query also supports the `resultType` query parameter.
`f`	The response format. The default response format is `html` . The values supported are defined by the `"supportedQueryFormats"` layer property. Values: `html` \| `json` \| `pbf` \| `geojson`

Considerations for `resultType`

The maxTileRecordCount and maxStandardRecordCount are determined by the server. 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 may vary based on the type of data (polygon, point, polyline, table).

The server advertises maxRecordCount with the layer metadata. For example, the following max record count is returned for points data:

Use dark colors for code blocksCopy
{"maxRecordCount": 2000, "tileMaxRecordCount": 8000, "standardMaxRecordCount": 32000}

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 .

Example usage

Example one: standard query

The following is a sample request URL that demonstrates how to query the last two deliveries made by an employee:

Use dark colors for code blocksCopy
https://organization.example.com/<context>/rest/services/Hosted/deliveries/FeatureServer/0/queryTopFeatures?where=&objectIds=&time=&topFilter={"groupByFields": "employeeName", "topCount": 2, "orderByFields": "deliveryNumber desc"}&geometry=&geometryType=esriGeometryEnvelope&inSR=&spatialRel=esriSpatialRelIntersects&distance=&units=esriSRUnit_Foot&outFields=employeeName,deliveryNumber&returnGeometry=true&maxAllowableOffset=&geometryPrecision=&outSR=&returnIdsOnly=false&returnCountOnly=false&returnExtentOnly=false&returnZ=false&returnM=false&resultType=&f=pjson

Example two: `resultType` of `none` , `maxRecordCount`

The following is a sample request URL used to demonstrate the none resultType value. Along with the none value, the maxRecordCount is always used ("maxRecordCount": 2000 ) or an overwritten value by the service owner or admin is used.

Use dark colors for code blocksCopy
https://organization.example.com/<context>/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 three: `resultType` of `standard` , `standardMaxRecordCount`

The following is a sample request URL used to demonstrate the standard resultType value. Along with the standard value, the standardMaxRecordCount is always used ("standardMaxRecordCount": 3200 ) for point and table layers.

Use dark colors for code blocksCopy
https://organization.example.com/<context>/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 four: `resultType` of `tile` , `tileMaxRecordCount`

The following is a sample request URL used to demonstrate the tile resultType value. Along with the tile value, the tileMaxRecordCount is always used ("tileMaxRecordCount": 8000 ) for point layers.

Use dark colors for code blocksCopy
https://organization.example.com/<context>/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

Use dark colors for code blocksCopy
{
  "exceededTransferLimit": <true | false>,
  "features: [<feature1, feature2>],
  "fields": [
    {
      "name": "<fieldName1>",
      "type": "<fieldType1>",
      "alias": "<fieldAlias1>",
      "length": "<length1>"
    },
    {
      "name": "<fieldName2>",
      "alias": "<fieldAlias2>",
      "type": "<fieldType2>",
      "length": "<length2>"
    }
  ],
 "geometryType": "<geometryType>",
 "spatialReference": {<spatialReference>},
 "globalIdFieldName": "<fieldName>",
 "objectIdFieldName": "<fieldName>",
 "hasZ": <true | false>,
 "hasM": <true | false>
}

JSON Response example

Use dark colors for code blocksCopy
{
  "exceededTransferLimit": false,
  "features": [
    {
      "attributes": {
        "employeeName": "Jason",
	       "deliveryNumber": 25
      },
      "geometry": {
        "x": -76.9505202472378,
        "y": 36.02168768903079
      }
    },
    {
      "attributes": {
        "employeeName": "Jason",
	       "deliveryNumber": 24
      },
      "geometry": {
        "x": -80.28022828451529,
        "y": 34.9904342763449
      }
    },
  ],
  "fields": [
    {
      "name": "employee",
      "alias": "employee",
      "type": "esriFieldTypeString",
      "length": 100
    },
    {
      "name": "deliveryNumber",
      "alias": "deliveryNumber",
      "type": "esriFieldTypeDouble",
      "length": 1000
    }
  ],
  "geometryType": "esriGeometryPoint",
  "spatialReference": {
    "wkid": 4326,
    "latestWkid": 4326
  },
  "globalIdFieldName": "globalid",
  "objectIdFieldName": "objectid",
  "hasZ": false,
  "hasM": false
}