Hide Table of Contents
esri
esri/arcgis
esri/dijit
esri/dijit/analysis
esri/dijit/geoenrichment
esri/dijit/geoenrichment/ReportPlayer
esri/geometry
esri/layers
esri/renderers
esri/symbols
esri/tasks
esri/tasks/datareviewer
esri/tasks/geoenrichment
esri/tasks/locationproviders
Class: Query
[ AMD Module Require | Legacy Module Require ]
dojo.require("esri.tasks.query");
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
| Name | Summary |
|---|---|
| new esri.tasks.Query() | Creates a new Query object used to execute a query on the layer resource identified by the URL. |
Constants
| Name | Description |
|---|---|
SPATIAL_REL_CONTAINS | Part or all of a feature from feature class 1 is contained within a feature from feature class 2. |
SPATIAL_REL_CROSSES | The feature from feature class 1 crosses a feature from feature class 2. |
SPATIAL_REL_ENVELOPEINTERSECTS | The envelope of feature class 1 intersects with the envelope of feature class 2. |
SPATIAL_REL_INDEXINTERSECTS | The envelope of the query feature class intersects the index entry for the target feature class. |
SPATIAL_REL_INTERSECTS | Part of a feature from feature class 1 is contained in a feature from feature class 2. |
SPATIAL_REL_OVERLAPS | Features from feature class 1 overlap features in feature class 2. |
SPATIAL_REL_RELATION | Allows specification of any relationship defined using the Shape Comparison Language. |
SPATIAL_REL_TOUCHES | The feature from feature class 1 touches the border of a feature from feature class 2. |
SPATIAL_REL_WITHIN | The feature from feature class 1 is completely enclosed by the feature from feature class 2. |
Properties
| Name | Type | Summary |
|---|---|---|
| cacheHint | Boolean | Indicates if the service should cache the query results. |
| distance | Number | Buffer distance for input geometries. |
| geometry | Geometry | The geometry to apply to the spatial filter. |
| geometryPrecision | Number | Specify the number of decimal places for the geometries returned by the query operation. |
| groupByFieldsForStatistics | String[] | One or more field names that will be used to group the statistics. |
| maxAllowableOffset | Number | The maximum allowable offset used for generalizing geometries returned by the query operation. |
| multipatchOption | String | Parameter to support querying feature services whose data source is a multipatch featureclass. |
| num | Number | Number of features to retrieve. |
| objectIds | Number[] | A comma delimited list of ObjectIds for the features in the layer/table that you want to query. |
| orderByFields | String[] | One or more field names that will be used to order the query results. |
| outFields | String[] | Attribute fields to include in the FeatureSet. |
| outSpatialReference | SpatialReference | The spatial reference for the returned geometry. |
| outStatistics | StatisticDefinition[] | The definitions for one or more field-based statistic to be calculated. |
| pixelSize | Symbol | Specify the pixel level to be identified on the x and y axis. |
| quantizationParameters | Object | 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. |
| relationParam | String | The 'Shape Comparison Language' string to evaluate. |
| returnDistinctValues | Boolean | If true then returns distinct values based on the fields specified in the outFields. |
| returnGeometry | Boolean | If "true", each feature in the FeatureSet includes the geometry. |
| spatialRelationship | String | The spatial relationship to be applied on the input geometry while performing the query. |
| start | Number | Zero-based index indicating where to begin retrieving features. |
| text | String | Shorthand for a where clause using "like". |
| timeExtent | TimeExtent | Specify a time extent for the query. |
| units | String | The unit for calculating the buffer distance. |
| where | String | A where clause for the query. |
Constructor Details
Creates a new Query object used to execute a query on the layer resource identified by the URL.
Sample:
var query = new esri.tasks.Query();
Property Details
<Boolean
BooleanIndicates if the service should cache the query results. It only applies if the layer's advancedQueryCapabilities.supportsCacheHint is
true. Use only for queries that have the same parameters every time the app is used. Some examples of cacheable queries:
- Queries that fetch statistics or features on app load.
- Queries based on preset input, for example, a drop-down list of US states.
- Queries based on preset extents, for example bookmarks, in web maps.
Known values:
true | falseDefault value:
false<Number
NumberBuffer 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
GeometryThe 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
NumberSpecify the number of decimal places for the geometries returned by the query operation. (Added at v3.0)
Sample:
query.geometryPrecision = 1;
<String[]
String[]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
NumberThe 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
StringParameter to support querying feature services whose data source is a multipatch featureclass. (Added at v3.12)
Known values:
xyFootprintSee also: FeatureLayer.multipatchOption
<Number
NumberNumber 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[]
Number[]A comma delimited list of ObjectIds for the features in the layer/table that you want to query. (Added at v2.0)
<String[]
String[]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.
Sample:
query.orderByFields = ["STATE_NAME DESC"];
<String[]
String[]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.
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
SpatialReferenceThe 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[]
StatisticDefinition[]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 then only a subset of query parameters are supported. The supported parameters depends on the version of your service. See the ArcGIS REST API documentation for details on which query parameters are supported at each version.
Sample:
var statisticDefinition = new esri.tasks.StatisticDefinition(); statisticDefinition.statisticType = "sum"; statisticDefinition.onStatisticField = "POP2000"; statisticDefinition.outStatisticFieldName = "TotalPop"; query.outStatistics = [statisticDefinition];
<Symbol
SymbolSpecify 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
ObjectUsed 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)
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>< |
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. |
< |
Required | Available value: "view". Geometry coordinates are optimized for viewing and displaying of data. |
< |
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. |
< |
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. |
<String
StringThe '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
BooleanIf 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 | falseDefault value:
false<Boolean
BooleanIf "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 | falseDefault value:
false<String
StringThe 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_INTERSECTSSample:
var query = new esri.tasks.Query(); query.spatialRelationship = esri.tasks.Query.SPATIAL_REL_CONTAINS;
<Number
NumberZero-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
StringShorthand 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
TimeExtentSpecify a time extent for the query. (Added at v2.0)
Sample:
var timeQuery = new esri.tasks.Query();
timeQuery.timeExtent = timeExtent;
layer.queryFeatures(timeQuery,function(featureSet) {});
<String
StringThe 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
StringA where clause for the query. Any legal SQL where clause operating on the fields in the layer is allowed.
Sample: Sring 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;