query

AMD: require(["esri/rest/query"], (query) => { /* code goes here */ });
ESM: import * as query from "@arcgis/core/rest/query.js";
Object: esri/rest/query
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
require([
  "esri/rest/query"
], function(query) {
  // url to the layer of interest to query
  let queryUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/SampleWorldCities/MapServer/0";

  query.executeQueryJSON(queryUrl, {  // autocasts as new Query()
     where: "POP > 1000000"
  }).then(function(results){
    // results is a FeatureSet containing an array of graphic features
    console.log(results.graphics);
  }, function(error){
       console.log(error); // will print error in console, if any
     });
});

Method Overview

Name Return Type Summary Object
Promise<object>

Query information about attachments associated with features from a feature layer specified in the url parameter.

more details
query
Promise<number>

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

more details
query
Promise<object>

Gets the extent of the features that satisfy the input query.

more details
query
Promise<number[]>

Executes a Query against the layer specified in the url parameter.

more details
query
Promise<number>

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

more details
query
Promise<object>

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

more details
query
Promise<number[]>

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

more details
query
Promise<FeatureSet>

Executes a Query against the layer specified in the url parameter.

more details
query
Promise<FeatureSet>

Executes a Query against the layer specified in the url parameter.

more details
query
Promise<object>

Executes a RelationshipQuery against the layer or table specified in the url parameter.

more details
query
Promise<FeatureSet>

Executes a TopFeaturesQuery against a feature service and returns a FeatureSet once the promise resolves.

more details
query

Method Details

executeAttachmentQuery(url, attachmentQuery, requestOptions){Promise<object>}

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.

Parameters
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 autocast
Autocasts from Object

Specifies the attachment parameters for query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<object> When resolved, returns an object containing AttachmentInfos grouped by the source feature objectIds.
See also
executeForCount(url, query, requestOptions){Promise<number>}

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

Parameters
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 autocast
Autocasts from Object

Specifies the attributes and spatial filter of the query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<number> When resolved, the result is the number of features that satisfy the input query.
Example
require([
  "esri/rest/query"
], function(query) {
  // url to the layer of interest to query
  let queryUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";

  query.executeForCount(queryUrl, {  // autocasts as new Query()
     where: "POP07_SQMI > 100"
  }).then(function(count){
    console.log(count, " features matched the input query");
  }, function(error){
       console.log(error); // will print error in console if unsupported layers are used
     });
});
executeForExtent(url, params, requestOptions){Promise<object>}

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.

Parameters
url String

URL to the ArcGIS Server REST resource that represents a feature layer (usually of a Feature Service Layer or Map Service Layer).

params Query

Specifies the attributes and spatial filter of the query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<object> 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 The extent of the features that satisfy the query.
executeForIds(url, query, requestOptions){Promise<number[]>}

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.

Parameters
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 autocast
Autocasts from Object

Specifies the attributes and spatial filter of the query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<number[]> When resolved, the result is an array of object IDs for features that satisfy the input query.
Example
require([
  "esri/rest/query"
], function(query) {
  // url to the layer of interest to query
  let queryUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";

  query.executeForIds(queryUrl, {  // autocasts as new Query()
     where: "SUB_REGION = 'Pacific'"
  }).then(function(results){
    console.log(results);  // an array of object IDs
  });
  ...
});
executeForTopCount(url, topFeaturesQuery, requestOptions){Promise<number>}
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.
Parameters
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 topFilter parameter must be set.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<number> When resolved, returns the number of features satisfying the query.
See also
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 = new TopFeaturesQuery({
  topFilter: new TopFilter({
    topCount: 1,
    groupByFields: ["Region"],
    orderByFields: ["Sales DESC"]
  })
});
executeForTopCount(url, query)
  .then(function(response){
     // returns the number of the features that have the most sales by region.
   });
executeForTopExtents(url, topFeaturesQuery, outSpatialReference, requestOptions){Promise<object>}
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.
Parameters
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 topFilter parameter must be set.

outSpatialReference SpatialReference

The desired output spatial reference.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<object> 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 The extent of features that satisfy the query.
See also
Example
// Get the count and extent of the three highest magnitude earthquakes
// in each region.
const query = new TopFeaturesQuery({
  where: "mag >= 6",
  geometry: studyExtent,
  topFilter: new TopFilter({
    topCount: 3,
    groupByFields: ["region"],
    orderByFields: ["mag DESC"]
  })
});
executeForTopExtents(url, query)
  .then(function(response){
     // returns the count and extent of top three earthquakes within each region
   });
executeForTopIds(url, topFeaturesQuery, outSpatialReference, requestOptions){Promise<number[]>}
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.
Parameters
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 topFilter parameter must be set.

outSpatialReference SpatialReference

The desired output spatial reference.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<number[]> When resolved, returns an array of numbers representing the object IDs of features satisfying the query.
See also
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 = new TopFeaturesQuery({
  where: "mag >= 6",
  topFilter: new TopFilter({
    topCount: 3,
    groupByFields: ["region"],
    orderByFields: ["mag DESC"]
  })
});
executeTopFeaturesQuery(url, query)
  .then(function(response){
     // returns an array of object ids of top three earthquakes within each region
   });
executeQueryJSON(url, query, requestOptions){Promise<FeatureSet>}

Executes a Query against the layer specified in the url parameter. The result is returned as a FeatureSet, which can be accessed using the .then() method. 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.

Parameters
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 autocast
Autocasts from Object

Specifies the attributes and spatial filter of the query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<FeatureSet> When resolved, a FeatureSet containing an array of graphic features is returned.
Example
require([
  "esri/rest/query", "esri/rest/support/Query"
], function(query, Query) {
  // url to the layer of interest to query
  let queryUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";

  // create the Query object
  let queryObject = new Query();
  queryObject.where = "STATE_NAME = 'Washington'";
  queryObject.outSpatialReference = { wkid:4269 };
  queryObject.returnGeometry = true;
  queryObject.outFields = [ "HOUSEHOLDS" ];

  // call the executeQueryJSON() method
  query.executeQueryJSON(queryUrl, queryObject).then(function(results){
    // results.graphics contains the graphics returned from query
  });
  ...
});
executeQueryPBF(url, query, requestOptions){Promise<FeatureSet>}

Executes a Query against the layer specified in the url parameter. The result is returned as a FeatureSet, which can be accessed using the .then() method. 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.

Parameters
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 autocast
Autocasts from Object

Specifies the attributes and spatial filter of the query.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<FeatureSet> When resolved, a FeatureSet containing an array of graphic features is returned.
Example
require([
  "esri/rest/query", "esri/rest/support/Query"
], function(query, Query) {
  // url to the layer of interest to query
  let queryUrl = "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Census/MapServer/3";

  // create the Query object
  let queryObject = new Query();
  queryObject.where = "STATE_NAME = 'Washington'";
  queryObject.outSpatialReference = { wkid:4269 };
  queryObject.returnGeometry = true;
  queryObject.outFields = [ "HOUSEHOLDS" ];

  // call the executeQueryPBF() method
  query.executeQueryPBF(queryUrl, queryObject).then(function(results){
    // results.graphics contains the graphics returned from query
  });
  ...
});
executeRelationshipQuery(url, relationshipQuery, requestOptions){Promise<object>}

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.

Parameters
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 autocast
Autocasts from Object

Specifies relationship parameters for querying related features or records from a layer or a table.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<object> 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
require([
  "esri/rest/query", "esri/rest/support/RelationshipQuery"
], function(query, RelationshipQuery) {
  // url to the layer of interest to query
  let queryUrl = "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
  query.executeRelationshipQuery(queryUrl, queryRelationship).then((results) => {
     console.log("query results", results);
  })
  .catch((error) => {
     console.log("query error", error);
  });
executeTopFeaturesQuery(url, topFeaturesQuery, outSpatialReference, requestOptions){Promise<FeatureSet>}
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.
Parameters
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 topFilter parameter must be set.

outSpatialReference SpatialReference

The desired output spatial reference.

requestOptions Object
optional

Additional options to be used for the data request (will override requestOptions defined during construction).

Returns
Type Description
Promise<FeatureSet> When resolved, returns a FeatureSet containing an array of features that are grouped and ordered specified fields.
See also
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 = new TopFeaturesQuery({
  outFields: ["State, TOTAL, Park"],
  topFilter: new TopFilter({
    topCount: 1,
    groupByFields: ["State"],
    orderByFields: ["TOTAL DESC"]
  })
});
executeTopFeaturesQuery(url, query)
  .then(function(response){
     // returns a feature set with features containing the most visited
     // national park in each state ordered by the number of visits.
     // The following attributes are returned as well: State, TOTAL, Park
   });

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.