query | References | ArcGIS Maps SDK for JavaScript

import { executeAttachmentQuery, executeForCount, executeForExtent, executeForIds, executeForTopCount } from "@arcgis/core/rest/query.js";

Since: ArcGIS Maps SDK for JavaScript 4.19

Executes different types of query operations on a layer. The most common method used is executeQueryJSON(), which executes the query for JSON results as defined in the Query object that is passed as a parameter to the function. executeQueryJSON() returns a Promise that resolves to a FeatureSet, which contains the features in the layer that satisfy the Query.

You can also obtain the number of features that satisfy the query, the extent of features, related features or records associated with a feature, attachments for features or the featureIds of features.

For example, when working with a feature layer of world cities, to obtain a FeatureSet of cities with a population greater than one million people, use the code below.

See also

Example

// query featureLayer for cities with a population greater than one million people
const query = await $arcgis.import("@arcgis/core/rest/query");

// url to the layer of interest to query
const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/SampleWorldCities/MapServer/0";

const { features } = await query.executeQueryJSON(url, {
  where: "POP > 1000000"
});

Functions

Name	Return Type	Object
`executeAttachmentQuery`	`Promise<Record<string, AttachmentInfo[]>>`
`executeForCount`	`Promise<number>`
`executeForExtent`	`Promise<{ count: number; extent: Extent \| null; }>`
`executeForIds`	`Promise<ObjectId[]>`
`executeForTopCount`	`Promise<number>`
`executeForTopExtents`	`Promise<{ count: number; extent: Extent \| null; }>`
`executeForTopIds`	`Promise<number[]>`
`executeQueryJSON`	`Promise<FeatureSet>`
`executeQueryPBF`	`Promise<FeatureSet>`
`executeRelationshipQuery`	`Promise<Record<string, FeatureSet>>`
`executeTopFeaturesQuery`	`Promise<FeatureSet>`

executeAttachmentQuery

Function

Query information about attachments associated with features from a feature layer specified in the url parameter. It will return an error if the layer's capabilities.data.supportsAttachment is set to false.

See also

Signature: executeAttachmentQuery (url: string, attachmentQuery: AttachmentQuery, requestOptions?: RequestOptions): Promise<Record<string, AttachmentInfo[]>>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
attachmentQuery	`AttachmentQuery`	Specifies the attachment parameters for query.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<Record<string, AttachmentInfo[]>>
When resolved, returns an object containing AttachmentInfos grouped by the source feature objectIds.

executeForCount

Function

Gets a count of the number of features that satisfy the input query.

Signature: executeForCount (url: string, query: Query | QueryProperties, requestOptions?: RequestOptions): Promise<number>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
query	`Query \| QueryProperties`	Specifies the attributes and spatial filter of the query.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<number>
When resolved, the result is the number of features that satisfy the input query.

Example

const query = await $arcgis.import("@arcgis/core/rest/query");

// url to the layer of interest to query
const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";

const count = await query.executeForCount(url, {
  where: "POP07_SQMI > 100"
});

executeForExtent

Function

Gets the extent of the features that satisfy the input query. The count of features that satisfy the input query is returned upon resolution as well.

Signature: executeForExtent (url: string, query: Query | QueryProperties, requestOptions?: RequestOptions): Promise<{ count: number; extent: Extent | null; }>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
query	`Query \| QueryProperties`	Specifies the attributes and spatial filter of the query.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns

Promise<{ count: number; extent: Extent | null; }>

When resolved, returns the extent and count of the features that satisfy the input query. See the object specification table below for details.

Property	Type	Description
count	number	The number of features that satisfy the input query.
extent	Extent \| null	The extent of the features that satisfy the query.

executeForIds

Function

Executes a Query against the layer specified in the url parameter. The result is an array of the object IDs of features that satisfy the input query. There is no limit to the number of object IDs returned in the ID array response.

Signature: executeForIds (url: string, query: Query | QueryProperties, requestOptions?: RequestOptions, layerMetadata?: LayerMetadata): Promise<ObjectId[]>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
query	`Query \| QueryProperties`	Specifies the attributes and spatial filter of the query.
requestOptions	`RequestOptions`	Additional options to be used for the data request.
layerMetadata	`LayerMetadata`	Additional query options.

Returns: Promise<ObjectId[]>
When resolved, the result is an array of object IDs for features that satisfy the input query.

Example

const query = await $arcgis.import("@arcgis/core/rest/query");

// url to the layer of interest to query
const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";

const ids = await query.executeForIds(url, {
  where: "SUB_REGION = 'Pacific'"
});
console.log(ids);  // an array of object IDs

executeForTopCount

Function

Since: ArcGIS Maps SDK for JavaScript 4.25

Executes a TopFeaturesQuery against a feature service and returns the count of features or records that satisfy the query.

Known Limitations

Currently, the executeForTopCount is only supported with server-side FeatureLayers.

See also

Signature: executeForTopCount (url: string, topFeaturesQuery: TopFeaturesQuery, requestOptions?: RequestOptions): Promise<number>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
topFeaturesQuery	`TopFeaturesQuery`	Specifies the attributes, spatial, temporal, and top filter of the query. The TopFeaturesQuery.topFilter parameter must be set.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<number>
When resolved, returns the number of features satisfying the query.

Example

// set the query to return a count
// of features that has most sales grouped by regions.
// top query will run against all features available in the service
const query = await $arcgis.import("@arcgis/core/rest/query");

const count = await query.executeForTopCount(url, { // autocast to TopFeaturesQuery
  where: "mag >= 6",
  topFilter: { // autocast to TopFilter
    topCount: 1,
    groupByFields: ["Region"],
    orderByFields: ["Sales DESC"],
  },
});

executeForTopExtents

Function

Since: ArcGIS Maps SDK for JavaScript 4.25

Executes a TopFeaturesQuery against a feature service and returns the Extent of features that satisfy the query.

Known Limitations

Currently, the executeForTopExtents is only supported with server-side FeatureLayers.

See also

Signature: executeForTopExtents (url: string, topFeaturesQuery: TopFeaturesQuery, requestOptions?: RequestOptions): Promise<{ count: number; extent: Extent | null; }>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
topFeaturesQuery	`TopFeaturesQuery`	Specifies the attributes, spatial, temporal, and top filter of the query. The TopFeaturesQuery.topFilter parameter must be set.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns

Promise<{ count: number; extent: Extent | null; }>

When resolved, returns the extent and count of the features that satisfy the input query. See the object specification table below for details.

Property	Type	Description
count	Number	The number of features that satisfy the query.
extent	Extent \| null	The extent of features that satisfy the query.

Example

// Get the count and extent of the three highest magnitude earthquakes in each region.

const query = await $arcgis.import("@arcgis/core/rest/query");

const { count, extent } = await query.executeForTopExtents(url, { // autocast to TopFeaturesQuery
  where: "mag >= 6",
  topFilter: { // autocast to TopFilter
    topCount: 3,
    groupByFields: ["region"],
    orderByFields: ["mag DESC"]
  }
});

executeForTopIds

Function

Since: ArcGIS Maps SDK for JavaScript 4.25

Executes a TopFeaturesQuery against a feature service and returns an array of Object IDs of features that satisfy the query.

Known Limitations

Currently, the executeForTopIds is only supported with server-side FeatureLayers.

See also

Signature: executeForTopIds (url: string, topFeaturesQuery: TopFeaturesQuery, requestOptions?: RequestOptions): Promise<number[]>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
topFeaturesQuery	`TopFeaturesQuery`	Specifies the attributes, spatial, temporal, and top filter of the query. The TopFeaturesQuery.topFilter parameter must be set.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<number[]>
When resolved, returns an array of numbers representing the object IDs of features satisfying the query.

Example

// Get the objectIds top three earthquakes
// grouped by regions and ordered by their magnitude levels
// top query will only run against earthquakes that have mag >=6.

const query = await $arcgis.import("@arcgis/core/rest/query");

const ids = await query.executeForTopIds(url, { // autocast to TopFeaturesQuery
  where: "mag >= 6",
  topFilter: { // autocast to TopFilter
    topCount: 3,
    groupByFields: ["region"],
    orderByFields: ["mag DESC"]
  }
});

executeQueryJSON

Function

Executes a Query against the layer specified in the url parameter. The result is returned as a FeatureSet containing an array of Graphic features, which can be added to the map. This array will not be populated if no results are found.

Signature: executeQueryJSON (url: string, query: Query | QueryProperties, requestOptions?: RequestOptions, layerMetadata?: LayerMetadata): Promise<FeatureSet>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
query	`Query \| QueryProperties`	Specifies the attributes and spatial filter of the query.
requestOptions	`RequestOptions`	Additional options to be used for the data request.
layerMetadata	`LayerMetadata`	Additional query options.

Returns: Promise<FeatureSet>
When resolved, a FeatureSet containing an array of graphic features is returned.

Example

const query = await $arcgis.import("@arcgis/core/rest/query");

const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";
const { features } = await query.executeQueryJSON(url, {
  where: "STATE_NAME = 'Washington'",
  outSpatialReference: { wkid: 4269 },
  returnGeometry: true,
  outFields: ["HOUSEHOLDS"],
});

executeQueryPBF

Function

Executes a Query against the layer specified in the url parameter. The result is returned as a FeatureSet. A FeatureSet contains an array of Graphic features, which can be added to the map. This array will not be populated if no results are found.

Signature: executeQueryPBF (url: string, query: Query | QueryProperties, requestOptions?: RequestOptions, layerMetadata?: LayerMetadata): Promise<FeatureSet>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
query	`Query \| QueryProperties`	Specifies the attributes and spatial filter of the query.
requestOptions	`RequestOptions`	Additional options to be used for the data request.
layerMetadata	`LayerMetadata`	Additional query options.

Returns: Promise<FeatureSet>
When resolved, a FeatureSet containing an array of graphics is returned.

Example

const query = await $arcgis.import("@arcgis/core/rest/query");

const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";
const { features } = await query.executeQueryPBF(url, {
  where: "STATE_NAME = 'Washington'",
  outSpatialReference: { wkid: 4269 },
  returnGeometry: true,
  outFields: ["HOUSEHOLDS"],
});

executeRelationshipQuery

Function

Executes a RelationshipQuery against the layer or table specified in the url parameter. If the query is successful, the returned results are FeatureSets grouped by source layer or table objectIds.

Signature: executeRelationshipQuery (url: string, relationshipQuery: RelationshipQuery, requestOptions?: RequestOptions): Promise<Record<string, FeatureSet>>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
relationshipQuery	`RelationshipQuery`	Specifies relationship parameters for querying related features or records from a layer or a table.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<Record<string, FeatureSet>>
When resolved, the results are FeatureSets grouped by source layer or table objectIds. Each FeatureSet contains an array of Graphic features including the values of the fields requested by the user.

Example

const [query, RelationshipQuery] = await $arcgis.import([
  "@arcgis/core/rest/query.js",
  "@arcgis/core/rest/support/RelationshipQuery.js",
]);

// url to the layer of interest to query
const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/0";

// specify relationship query parameter
const queryRelationship = new RelationshipQuery({
   outFields: ["*"],
   relationshipId: relationshipId,
   objectIds: [11, 22]
});

// query related features that meet the query parameters
const featureSet = await query.executeRelationshipQuery(url, queryRelationship);
console.log("query results", featureSet);

executeTopFeaturesQuery

Function

Since: ArcGIS Maps SDK for JavaScript 4.25

Executes a TopFeaturesQuery against a feature service and returns a FeatureSet once the promise resolves. The FeatureSet contains an array of top features grouped and ordered by specified fields. For example, you can call this method to query top three counties grouped by state names while ordering them based on their populations in a descending order.

Known Limitations

Currently, the executeTopFeaturesQuery is only supported with server-side FeatureLayers.

See also

Signature: executeTopFeaturesQuery (url: string, topFeaturesQuery: TopFeaturesQuery, outSpatialReference: SpatialReference, requestOptions?: RequestOptions): Promise<FeatureSet>

Parameters

Parameter	Type	Description
url	`string`	URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).
topFeaturesQuery	`TopFeaturesQuery`	Specifies the attributes, spatial, temporal, and top filter of the query. The TopFeaturesQuery.topFilter parameter must be set.
outSpatialReference	`SpatialReference`	The desired output spatial reference.
requestOptions	`RequestOptions`	Additional options to be used for the data request.

Returns: Promise<FeatureSet>
When resolved, returns a FeatureSet containing an array of features that are grouped and ordered specified fields.

Example

// Query the most visited national parks in each state
// and order them by the most visited
// query will run against all features available in the service

const query = await $arcgis.import("@arcgis/core/rest/query");

const url = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";
const { features } = await query.executeTopFeaturesQuery(url, { // autocast to TopFeaturesQuery
  outFields: ["State, TOTAL, Park"],
  topFilter: {  // autocast to TopFilter
    topCount: 1,
    groupByFields: ["State"],
    orderByFields: ["TOTAL DESC"]
  },
});