Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: Query

require(["esri/tasks/query"], function(Query) { /* code goes here */ });

Description

(Added at v1.0)
Query for input to the QueryTask. Not all query properties are required to execute a QueryTask. The query definition requires one of the following properties: queryGeometry, text, or where. Optional properties include outFields, outSpatialReference, and returnGeometry.

Samples

Search for samples that use this class.

Constructors

NameSummary
new Query()Creates a new Query object used to execute a query on the layer resource identified by the URL.

Constants

NameDescription
SPATIAL_REL_CONTAINSPart or all of a feature from feature class 1 is contained within a feature from feature class 2.
SPATIAL_REL_CROSSESThe feature from feature class 1 crosses a feature from feature class 2.
SPATIAL_REL_ENVELOPEINTERSECTSThe envelope of feature class 1 intersects with the envelope of feature class 2.
SPATIAL_REL_INDEXINTERSECTSThe envelope of the query feature class intersects the index entry for the target feature class.
SPATIAL_REL_INTERSECTSPart of a feature from feature class 1 is contained in a feature from feature class 2.
SPATIAL_REL_OVERLAPSFeatures from feature class 1 overlap features in feature class 2.
SPATIAL_REL_RELATIONAllows specification of any relationship defined using the Shape Comparison Language.
SPATIAL_REL_TOUCHESThe feature from feature class 1 touches the border of a feature from feature class 2.
SPATIAL_REL_WITHINThe feature from feature class 1 is completely enclosed by the feature from feature class 2.

Properties

NameTypeSummary
distanceNumberBuffer distance for input geometries.
geometryGeometryThe geometry to apply to the spatial filter.
geometryPrecisionNumberSpecify 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.
maxAllowableOffsetNumberThe maximum allowable offset used for generalizing geometries returned by the query operation.
multipatchOptionStringParameter to support querying feature services whose data source is a multipatch featureclass.
numNumberNumber of features to retrieve.
objectIdsNumber[]A comma delimited list of ObjectIds for the features in the layer/table that you want to query.
orderByFieldsString[]One or more field names that will be used to order the query results.
outFieldsString[]Attribute fields to include in the FeatureSet.
outSpatialReferenceSpatialReferenceThe spatial reference for the returned geometry.
outStatisticsStatisticDefinition[]The definitions for one or more field-based statistic to be calculated.
pixelSizeSymbolSpecify the pixel level to be identified on the x and y axis.
quantizationParametersObjectUsed to project the geometry onto a virtual grid, likely representing pixels on the screen.
Note:Quantization parameter only works with ArcGIS Online hosted services.
See the object specifications table below for the structure of the quantizationParameters object.
relationParamStringThe 'Shape Comparison Language' string to evaluate.
returnDistinctValuesBooleanIf true then returns distinct values based on the fields specified in the outFields.
returnGeometryBooleanIf "true", each feature in the FeatureSet includes the geometry.
spatialRelationshipStringThe spatial relationship to be applied on the input geometry while performing the query.
startNumberZero-based index indicating where to begin retrieving features.
textStringShorthand for a where clause using "like".
timeExtentTimeExtentSpecify a time extent for the query.
unitsStringThe unit for calculating the buffer distance.
whereStringA where clause for the query.
Constructor Details

new Query()

Creates a new Query object used to execute a query on the layer resource identified by the URL.
Sample:
require([
  "esri/tasks/query", ... 
], function(Query, ... ) {
  var query = new Query();
  ...
});
Property Details

<Number> distance

Buffer distance for input geometries. The distance unit is specified by query.units. Query results will include features within the distance specified of the query.geometry. This parameter only applies if FeatureLayer.supportsQueryWithDistance is true. It can be used with hosted features services in addition to map and feature services hosted by ArcGIS for Server 10.31 onward. Optional. (Added at v3.9)

<Geometry> geometry

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.

Sample:
function executeQueryTask(event) {
  // When the user clicks on a map, the onClick event returns the event point 
  // where the user clicked. The event contains mapPoint (esri.geometry.Point)

  query.geometry = event.mapPoint;

  //Execute task
  queryTask.execute(query, showResults);
}

<Number> geometryPrecision

Specify the number of decimal places for the geometries returned by the query operation. (Added at v3.0)
Sample:

query.geometryPrecision = 1;

<String[]> groupByFieldsForStatistics

One or more field names that will be used to group the statistics. groupByFieldsForStatistics is only valid when outStatistics have been defined. As of version 3.16, standard SQL expressions may also be used in place of field names when grouping by fields and querying hosted feature services for statistics. (Added at v2.6)
Sample:
query.groupByFieldsForStatistics = ["SUB_REGION"];

<Number> maxAllowableOffset

The maximum allowable offset used for generalizing geometries returned by the query operation. The offset is in the units of the spatialReference. If a spatialReference is not defined the spatial reference of the map is used. (Added at v2.0)

<String> multipatchOption

Parameter to support querying feature services whose data source is a multipatch featureclass. (Added at v3.12)
Known values: xyFootprint
Sample:
function queryTaskExecuteCompleteHandler(queryResults){
  console.log("complete", queryResults);
}

function queryTaskErrorHandler(queryError){
  console.log("error", queryError.error.details);
}

var queryTask = new QueryTask("http://servername.fqdn.suffix/arcgis/rest/services/Hosted/pasadena/FeatureServer/0");
var query = new Query();
query.objectIds = [22];
query.multipatchOption = "xyFootprint";
query.outFields = ["*"];
query.returnGeometry = true;
queryTask.on("complete", queryTaskExecuteCompleteHandler);
queryTask.on("error", queryTaskErrorHandler);
queryTask.execute(query);

<Number> num

Number of features to retrieve. Should be used in conjunction with query.start. 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. It can be used with hosted features services in addition to map and feature services hosted by ArcGIS for Server that support pagination (versions 10.3.1 or higher). (Added at v3.9)

<Number[]> objectIds

A comma delimited list of ObjectIds for the features in the layer/table that you want to query. (Added at v2.0)

<String[]> orderByFields

One or more field names that will be used to order the query results. Specifiy ASC (ascending) or DESC (descending) after the field name to control the order. The default order is ASC. orderByFields is only supported on dynamic layers and tables where supportsAdvancedQueries is true. As of version 3.16, standard SQL expressions may also be used in place of field names when ordering by fields in statistic queries on hosted feature services.

(Added at v2.6)
Sample:
query.orderByFields = ["STATE_NAME DESC"];

<String[]> outFields

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

When you specify 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, but your list of fields does not need to include these two fields.
Sample:
query.outFields = ["NAME", "STATE_ABBR", "POP04"];

<SpatialReference> outSpatialReference

The spatial reference for the returned geometry. If not specified, the geometry is returned in the spatial reference of its layer. See Projected Coordinate Systems and Geographic Coordinate Systems for the list of supported spatial references.

<StatisticDefinition[]> outStatistics

The definitions for one or more field-based statistic to be calculated. outStatistics is only supported on layers/tables where supportsStatistics is true. If outStatistics is specified the only other query parameters that will be used are groupByFieldsForStatistics, orderByFields, text, timeExtent and where.

Requires ArcGIS Server service version 10.1 or greater (Added at v2.6)
Sample:
require([
  "esri/tasks/query", "esri/tasks/StatisticDefinition", ... 
], function(Query, StatisticDefinition, ... ) {
  var query = new Query();
  var statisticDefinition = new StatisticDefinition();
  statisticDefinition.statisticType = "sum";
  statisticDefinition.onStatisticField = "POP2000";
  statisticDefinition.outStatisticFieldName = "TotalPop";

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

<Symbol> pixelSize

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. (Added at v3.5)

<Object> quantizationParameters

Used to project the geometry onto a virtual grid, likely representing pixels on the screen.
Note:Quantization parameter only works with ArcGIS Online hosted services.
See the object specifications table below for the structure of the quantizationParameters object. (Added at v3.12)
Object Specifications:
<quantizationParameters>
<Extent> extent Required 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.
<String> mode Required Available value: "view". Geometry coordinates are optimized for viewing and displaying of data.
<String> originPosition Required Available value: "upperLeft" or "lowerLeft". Integer's coordinates will be returned relative to the origin position defined by this property value. Default is upperLeft origin position.
<Number> tolerance Required The tolerance is the size of one pixel in the outSpatialReference units, this number is used to convert the coordinates to integers by building a grid with 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 tolerance is in the units of outSpatialReference. If outSpatialReference is not specified, then tolerance is assumed to be in the unit of the spatial reference of the layer. If the tolerance is not specified, the maxAllowableOffset is used. If the tolerance and maxAllowableOffset are not specified, a default 10,000 * 10,000 grid is used.
Sample:
var query = new Query();
query.quantizationParameters = {
  mode: "view",
  originPosition: "upperLeft",
  tolerance: 4820,
  extent: layer.fullExtent
};

<String> relationParam

The 'Shape Comparison Language' string to evaluate. Examples of valid strings are:

RELATE(G1,G2,"FFFTTT***)
dim (g1.boundary,g2.boundary) = linear
dim (g1.exterior, g2.boundary)= linear

The string describes the spatial relationship to be tested when the spatial relationship is esriSpatialRelRelation The Shape Comparison Language EDN topic has additional details.

<Boolean> returnDistinctValues

If true then returns distinct values based on the fields specified in the outFields. This parameter applies only if supportsAdvancedQueries property of the layer is true. Requires ArcGIS Server 10.1 Service Pack 1 or later. (Added at v3.11)
Known values: true | false
Default value: false

<Boolean> returnGeometry

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 makes up a significant portion of the response.
Known values: true | false
Default value: false

<String> spatialRelationship

The spatial relationship to be applied on the input geometry while performing the query. The valid values are listed in the Constants table.
Default value: SPATIAL_REL_INTERSECTS
Sample:
require([
  "esri/tasks/query", ... 
], function(Query, ... ) {
  var query = new Query();
  query.spatialRelationship = Query.SPATIAL_REL_CONTAINS;
  ...
});

<Number> start

Zero-based index indicating where to begin retrieving features. Should be used in conjunction with query.num. Use this to implement paging and retrieve "pages" of results when querying. Features are sorted ascending by their object ID field by default. This can be used with hosted features services in addition to map and feature services hosted by ArcGIS for Server that support pagination (versions 10.3.1 or higher). (Added at v3.9)

<String> text

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 Services Directory.
Sample:
query.text = stateName;

<TimeExtent> timeExtent

Specify a time extent for the query. (Added at v2.0)
Sample:
require([
  "esri/layers/FeatureLayer", "esri/TimeExtent", "esri/tasks/query", ... 
], function(FeatureLayer, TimeExtent, Query, ... ) {
  var layer = new FeatureLayer( ... );
  var timeExtent = new TimeExtent( ... );
  var timeQuery = new Query();
  timeQuery.timeExtent = timeExtent;
  layer.queryFeatures(timeQuery,function(featureSet) {});
  ...
});

<String> units

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 FeatureLayer.supportsQueryWithDistance is true. It can be used with hosted features services in addition to map and feature services hosted by ArcGIS for Server 10.31 onward. Optional. (Added at v3.9)
Known values: "feet" | "miles" | "nautical-miles" | "us-nautical-miles" | "meters" | "kilometers"

<String> where

A where clause for the query. Any legal SQL where clause operating on the fields in the layer is allowed.
Sample: String query example. Be sure you have the correct sequence of single and double quotes when writing the where clause in JavaScript.
  query.where = "NAME = '" + stateName + "'"; 
		
Number query example.
  query.where = "POP04 > " + population;