require(["esri/tasks/support/Query"], function(Query) { /* code goes here */ });
Class: esri/tasks/support/Query
Inheritance: Query Accessor
Since: ArcGIS API for JavaScript 4.0

Requirements: ArcGIS Online hosted feature service(s) or ArcGIS Server service(s) 10.1 or greater.

Query is used to define parameters to filter a layer's features, either by its attributes or its geometry. Once a Query object is created, you can set its properties to conform to the filtering requirements of the application. Once a Query object is created and its properties are set, it is then ready to be passed into an executable function in QueryTask (e.g. QueryTask.execute(Query)). The returned result is often a FeatureSet.

For example, you may want to view features in your map based on attribute values specified by the user (e.g. User inputs a state name to zoom to the state). To do this, create a query object and use the where property to query an attribute using SQL:

require(["esri/tasks/QueryTask", "esri/tasks/support/Query"], function(QueryTask, Query){
  var queryStatesTask  = new QueryTask({
    url: "..."  // URL of a feature layer representing U.S. states
  });
  var query = new Query();
  query.where = "STATE_NAME = 'California'";
  queryStatesTask.execute(query).then(function(result){
    // Do something with the resulting FeatureSet (zoom to it, highlight features, get other attributes, etc)
   });
});

Querying by geometry/location is also possible with Query. Instead of using where, use geometry. For example, let's say you want to build an application that highlights all the cities in a Feature Layer that are within 100 miles of a click on the view. You would set the geometry to the view click and the distance to 100:

require(["esri/tasks/QueryTask", "esri/tasks/support/Query"], function(QueryTask, Query){
  var queryCitiesTask = new QueryTask({
    url: "..."  // URL of a feature layer representing U.S. cities
  });
  var query = new Query();
  query.geometry = mapPoint; // mapPoint obtained from view-click event.
  query.distance = 100;
  query.units = "miles";
  query.spatialRelationship = "intersects"; // All features that intersect 100mi buffer
  queryCitiesTask.execute(query).then(function(result){
    // Returns all U.S. cities as a FeatureSet within 100 miles of view-click
  });
});
See also:

Constructors

new Query(properties)

Parameter:
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
NameTypeSummaryClass
String

The name of the class.

more details
more detailsAccessor
Number

Buffer distance for input geometries.

more details
more detailsQuery
Geometry

The geometry to apply to the spatial filter.

more details
more detailsQuery
Number

Specify the number of decimal places for the geometries returned by the query operation.

more details
more detailsQuery
String[]

One or more field names that will be used to group the statistics.

more details
more detailsQuery
Number

The maximum allowable offset used for generalizing geometries returned by the query operation.

more details
more detailsQuery
String

Parameter dictates how the geometry of a multipatch feature will be returned.

more details
more detailsQuery
Number

Number of features to retrieve.

more details
more detailsQuery
Number[]

A comma delimited list of ObjectIds for the features in the layer/table being queried.

more details
more detailsQuery
String[]

One or more field names that will be used to order the query results.

more details
more detailsQuery
String[]

Attribute fields to include in the FeatureSet.

more details
more detailsQuery
SpatialReference

The spatial reference for the returned geometry.

more details
more detailsQuery
StatisticDefinition[]

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

more details
more detailsQuery
Symbol

Specify the pixel level to be identified on the X and Y axis.

more details
more detailsQuery
Object

Used to project the geometry onto a virtual grid, likely representing pixels on the screen.

more details
more detailsQuery
String

The string describes the spatial relationship to be tested when the spatial relationship is relation.

more details
more detailsQuery
Boolean

If true then the query returns distinct values based on the fields specified in outFields.

more details
more detailsQuery
Boolean

If true, each feature in the FeatureSet includes the geometry.

more details
more detailsQuery
Boolean

Set this property to true to include the z-values of each feature in the response FeatureSet.

more details
more detailsQuery
String

The spatial relationship to be applied to the input geometry while performing the query.

more details
more detailsQuery
Number

Zero-based index indicating where to begin retrieving features.

more details
more detailsQuery
String

Shorthand for a where clause using "like".

more details
more detailsQuery
String

The unit for calculating the buffer distance.

more details
more detailsQuery
String

A where clause for the query.

more details
more detailsQuery

Property Details

declaredClassStringreadonly inherited

The name of the class. The declared class name is formatted as esri.folder.className.

distanceNumber

Buffer distance for input geometries. The distance unit is specified by units property. Query results will include features within the distance specified of the geometry of the query. This parameter only applies if supportsQueryWithDistance is true.

geometryGeometry

The geometry to apply to the spatial filter. The spatial relationship as specified by spatialRelationship is applied to this geometry while performing the query. The valid geometry types are Extent, Point, Multipoint, Polyline, or Polygon.

geometryPrecisionNumber

Specify the number of decimal places for the geometries returned by the query operation.

groupByFieldsForStatisticsString[]

One or more field names that will be used to group the statistics. This is only valid when outStatistics has been defined. Requires ArcGIS Server service version 10.1 or greater.

maxAllowableOffsetNumber

The maximum allowable offset used for generalizing geometries returned by the query operation. The offset is in the units of spatialReference. If spatialReference is not defined the spatial reference of the map is used.

multipatchOptionString

Parameter dictates how the geometry of a multipatch feature will be returned. Currently, the only supported value is xyFootprint and the xy footprint of each multipatch geometry will be returned in the result.

Example:
var queryTask = new QueryTask( ... );
var query = new Query();
query.objectIds = [22];
query.multipatchOption = "xyFootprint";
query.outFields = ["*"];
query.returnGeometry = true;
queryTask.execute(query);

Number of features to retrieve. Should be used in conjunction with start property. Use this to implement paging and retrieve "pages" of results when querying. If not provided, but an instance of Query has a start property, num defaults to 10.

Default Value: 10

objectIdsNumber[]

A comma delimited list of ObjectIds for the features in the layer/table being queried.

orderByFieldsString[]

One or more field names that will be used to order the query results. Specfiy ASC (ascending) or DESC (descending) after the field name to control the order. The default order is ASC. orderByFields is only supported on MapImageLayers and tables where supportsAdvancedQueries = true. Requires ArcGIS Server service version 10.1 or greater.

Example:
query.orderByFields = ["STATE_NAME DESC"];

outFieldsString[]

Attribute fields to include in the FeatureSet. Fields must exist in the map layer. You must list actual field names rather than the alias names. You are, however, able to use the alias names when you display the results. You can set field alias names in the map document.

When specifying the output fields, you should limit the fields to only those you expect to use in the query or the results. The fewer fields you include, the faster the response will be.

Each query must have access to the Shape and ObjectId fields for a layer. However, your list of fields does not need to include these two fields.

Example:
query.outFields = ["NAME", "STATE_ABBR", "POP04"];

outSpatialReferenceSpatialReference

The spatial reference for the returned geometry. If not specified, the geometry is returned in the spatial reference of the map.

The definitions for one or more field-based statistics to be calculated. outStatistics is only supported on layers/tables where supportsStatistics = true. If outStatistics is specified the only other query parameters that will be used are groupByFieldsForStatistics, orderByFields, text and where. Requires ArcGIS Server service version 10.1 or greater.

Example:
require([
  "esri/tasks/support/Query", "esri/tasks/support/StatisticDefinition", ...
], function(Query, StatisticDefinition, ... ) {
  var query = new Query();
  var statisticDefinition = new StatisticDefinition();
  statisticDefinition.statisticType = "sum";
  statisticDefinition.onStatisticField = "POP2000";
  statisticDefinition.outStatisticFieldName = "TotalPop";

  query.outStatistics = [statisticDefinition];
  ...
});

pixelSizeSymbol

Specify the pixel level to be identified on the X and Y axis. Defaults to the base resolution of the dataset if not specified. Applicable only to Image Service layers.

quantizationParametersObject

Used to project the geometry onto a virtual grid, likely representing pixels on the screen. Only works with ArcGIS Online hosted services.

Properties:
extent Extent
optional

An extent defining the quantization grid bounds. Its SpatialReference matches the input geometry spatial reference if one is specified for the query. Otherwise, the extent will be in the layer's spatial reference.

mode String
optional

Geometry coordinates are optimized for viewing and displaying of data. Known Values: view

originPosition String
optional

The integer's coordinates will be returned relative to the origin position defined by this property value. Default is upper-left. Known Values: upper-left | lower-left

tolerance Number
optional

The size of one pixel in the units of outSpatialReference. This number is used to convert coordinates to integers by building a grid with a resolution matching the tolerance. Each coordinate is then snapped to one pixel on the grid. Consecutive coordinates snapped to the same pixel are removed for reducing the overall response size. The units of tolerance will match the units of outSpatialReference. If outSpatialReference is not specified, then tolerance is assumed to be in the units of the spatial reference of the layer. If tolerance is not specified, the maxAllowableOffset is used. If tolerance and maxAllowableOffset are not specified, a grid of 10,000 * 10,000 grid is used by default.

Example:
var query = new Query();
query.quantizationParameters = {
  mode: "view",
  originPosition: "upper-left",
  tolerance: 4820,
  extent: layer.fullExtent
};

relationParamString

The string describes the spatial relationship to be tested when the spatial relationship is relation. The Relational functions for ST_Geometry topic has additional details.

Example:
var query = new Query();
query.relationParam = "FFFTTT***";

returnDistinctValuesBoolean

If true then the query returns distinct values based on the fields specified in outFields. This parameter applies only if supportsAdvancedQueries property of the layer is true. Requires ArcGIS Server 10.1 Service Pack 1 or later.

Default Value: false

returnGeometryBoolean

If true, each feature in the FeatureSet includes the geometry. Set to false (default) if you do not plan to include highlighted features on a map since the geometry takes up a significant portion of the response.

Default Value: false

returnZBoolean

Set this property to true to include the z-values of each feature in the response FeatureSet. The returnGeometry property must also be set to true for this property to have an effect.

Default Value: false

spatialRelationshipString

The spatial relationship to be applied to the input geometry while performing the query. The valid values are listed in the table below:

ValueDescription
intersectsPart of a feature from feature class 1 intersects a feature from feature class 2.
containsPart or all of a feature from feature class 1 is contained within a feature from feature class 2.
crossesThe feature from feature class 1 crosses a feature from feature class 2.
envelope-intersectsThe envelope of feature class 1 intersects with the envelope of feature class 2.
index-intersectsThe envelope of the query feature class intersects the index entry for the target feature class.
overlapsFeatures from feature class 1 overlap features in feature class 2.
touchesThe feature from feature class 1 touches the border of a feature from feature class 2.
withinThe feature from feature class 1 is completely enclosed by the feature from feature class 2.
relationAllows specification of any relationship defined using the Shape Comparison Language.
Default Value: intersects
Example:
require([
  "esri/tasks/support/Query", ...
], function(Query, ... ) {
  var query = new Query();
  query.spatialRelationship = "contains";
  ...
});

startNumber

Zero-based index indicating where to begin retrieving features. Should be used in conjunction with num property. Use this to implement paging and retrieve "pages" of results when querying. Features are sorted ascending by object ID by default.

textString

Shorthand for a where clause using "like". The field used is the display field defined in the map document. You can determine what the display field is for a layer in the Services Directory.

Example:
query.text = stateName;

unitsString

The unit for calculating the buffer distance. if unit 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 spatial reference. This parameter only applies if supportsQueryWithDistance is true.

Known Values: feet | miles | nautical-miles | us-nautical-miles | meters | kilometers

whereString

A where clause for the query. Any legal SQL where clause operating on the fields in the layer is allowed. Be sure to have the correct sequence of single and double quotes when writing the where clause in JavaScript.

Examples:
query.where = "NAME = '" + stateName + "'";
query.where = "POP04 > " + population;

Method Overview

NameReturn TypeSummaryClass
Object

Converts an instance of this class to its ArcGIS Portal JSON representation.

more details
more detailsQuery

Method Details

toJSON(){Object}

Converts an instance of this class to its ArcGIS Portal JSON representation. See the Using fromJSON() topic in the Guide for more information.

Returns:
TypeDescription
ObjectThe ArcGIS Portal JSON representation of an instance of this class.

API Reference search results

NameTypeModule

There were no match results from your search criteria.