AttributeBinsQuery

AMD: require(["esri/rest/support/AttributeBinsQuery"], (AttributeBinsQuery) => { /* code goes here */ });
ESM: import AttributeBinsQuery from "@arcgis/core/rest/support/AttributeBinsQuery.js";
Class: esri/rest/support/AttributeBinsQuery
Inheritance: AttributeBinsQueryAccessor
Since: ArcGIS Maps SDK for JavaScript 4.32

This class configures parameters for the queryAttributeBins() method, which groups features in a layer or layer view into bins based on numeric or date fields. This operation is useful for summarizing and analyzing large datasets by organizing them into meaningful groups, or bins, making it easier to detect patterns, trends, and anomalies across different ranges or time periods.

The binParameters property defines bin characteristics like size and start value, while the outStatistics parameter specifies the information each bin provides. Features can be filtered using a where condition and a spatial filter. Bins are arranged consecutively with no gaps: they are left-inclusive and right-exclusive, except for the last bin, which is right-inclusive. The method supports multiple statistical aggregations per bin and defaults to a histogram of value frequencies/counts if no specific aggregations are provided in outStatistics.

Bins are defined using one of the bin parameters, each supporting distinct parameters for handling boundaries between bins. Understanding the purpose of each bin parameter is crucial for understanding binning and boundary settings. There are four types of bin parameters:

Bin parameter type Description
AutoIntervalBinParameters You specify the number of bins, start and end values of the binning. The bin size is calculated by dividing the dataset's range by this number of bins.
FixedBoundariesBinParameters The bins strictly follow the specified input values. The first item in the array specifies the lower boundary of the first bin, while the last item specifies the upper boundary of the last bin. Intermediate values represent the lower boundaries of each bin.
FixedIntervalBinParameters The number of bins is not important, but the interval size must match the input data. Each bin will cover a range that exactly fits the specified interval.
DateBinParameters The intervals are based on calendar units. For example, with monthly intervals, each bin represents an entire month.
See also

Constructors

AttributeBinsQuery

Constructor
new AttributeBinsQuery(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 Watch for changes topic.
Show inherited properties Hide inherited properties
Name Type Summary Class

Bins can be returned in ascending or descending order.

AttributeBinsQuery

Bin parameters describe the characteristics of the bins, including their size and starting value.

AttributeBinsQuery

Indicates if the service should cache the query results.

AttributeBinsQuery

Datum transformation used for projecting geometries in the query results when outSpatialReference is different than the layer's spatial reference.

AttributeBinsQuery

The name of the class.

Accessor

Specifies a search distance from a given geometry in a spatial query.

AttributeBinsQuery

The geometry to apply to the spatial filter.

AttributeBinsQuery

Sets the name of the lower boundary property in the response.

AttributeBinsQuery

The spatial reference for the returned geometry.

AttributeBinsQuery

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

AttributeBinsQuery

Defines the IANA time zone used for bin calculations when the bin parameter field is a date field.

AttributeBinsQuery

If true then the query returns distinct values based on the field(s) specified in outFields.

AttributeBinsQuery

For spatial queries, this parameter defines the spatial relationship to query features in the layer or layer view against the input geometry.

AttributeBinsQuery

A time extent for a temporal query against time-aware layers.

AttributeBinsQuery

The unit for calculating the buffer distance when distance is specified in spatial queries.

AttributeBinsQuery

Sets the name of the upper boundary property in the response.

AttributeBinsQuery

A where clause for the query.

AttributeBinsQuery

Property Details

binOrder

Property
binOrder String |null |undefined

Bins can be returned in ascending or descending order. The default is ascending.

Possible Values:"ascending" |"descending"

Default Value:"ascending"

Bin parameters describe the characteristics of the bins, including their size and starting value. Each bin's size can either be specified by a parameter or calculated dynamically. Additionally, bins can be based on either date or numeric values.

Default Value:null

cacheHint

Property
cacheHint Boolean |null |undefined

Indicates if the service should cache the query results. It only applies if the layer's capabilities.query.supportsCacheHint is set to true. Use only for queries that have the same parameters every time the app is used. Some examples of cacheable queries:

Default Value:undefined

datumTransformation

Property
datumTransformation Number |SimpleTransformation |CompositeTransformation |null |undefined

Datum transformation used for projecting geometries in the query results when outSpatialReference is different than the layer's spatial reference. Requires ArcGIS Server service 10.5 or greater.

declaredClass

Inherited
Property
declaredClass Stringreadonly
Inherited from Accessor

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

distance

Property
distance Number |null |undefined

Specifies a search distance from a given geometry in a spatial query. The units property indicates the unit of measurement. In essence, setting this property creates a buffer at the specified size around the input geometry. The query will use that buffer to return features in the layer or layer view that adhere to the to the indicated spatial relationship.

If querying a feature service, the supportsQueryWithDistance capability must be true.

geometry

Property
geometry GeometryUnion |null |undefinedautocast

The geometry to apply to the spatial filter. The spatialRelationship will indicate how the geometry should be used to query features.

Known Limitations

Mesh geometry types are currently not supported.

lowerBoundaryAlias

Property
lowerBoundaryAlias String |null |undefined

Sets the name of the lower boundary property in the response. By default, the lower boundary is name lowerBoundary and indicates the value at the edge of each bin.

Default Value:null

outSpatialReference

Property
outSpatialReference SpatialReference |null |undefinedautocast

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

outStatistics

Property
outStatistics StatisticDefinition[] |null |undefinedautocast
Autocasts from Object[]

The definitions for one or more field-based statistics to be calculated. For service-based queries, check the layer's queryAttributeBins.supportedStatistics capabilities to ensure that the layer supports statistics queries.

Example
// get the average temperature for each bin
let statisticDefinition = new StatisticDefinition({
  statisticType: "avg",
  onStatisticField: "temp",
  outStatisticFieldName: "temp_avg"
});

// Query bins with fixed interval bin parameters based on field "temp" with 5 degrees interval.
const binQuery = new AttributeBinsQuery({
  binParameters: new FixedIntervalBinParameters({
    interval: 5, // the interval size for each bin. In this case, 5 degrees celsius
    field: "temp", // the field to bin, containing the temperature data
    start: 0, // the lower boundary of the first bin. 0 degrees celsius
    end: 30 // the upper boundary of the last bin. 30 degrees celsius
  }),
 // get the average temperature for each bin
 outStatistics: [statisticDefinition]
});

outTimeZone

Property
outTimeZone String |null |undefined

Defines the IANA time zone used for bin calculations when the bin parameter field is a date field. If not specified, the UTC time zone is used for binning calculations. When a time zone is specified, dates and times will be adjusted according to that IANA time zone.

Example
// Query bins with date interval bin parameters based on field "date" with monthly intervals.
const binQuery = new AttributeBinsQuery({
  binParameters: new DateBinParameters({
    interval: 3,
    field: "RecordedDate",
    start: new Date(Date.UTC(1980, 0, 2, 0, 0)),
    end: new Date(Date.UTC(1980, 2, 1, 0, 0)),
    number: "1",
    unit: "months"
  }),
  outTimeZone: "America/New_York" // Get the binning results in Eastern Time Zone
});

returnDistinctValues

Property
returnDistinctValues Boolean |null |undefined

If true then the query returns distinct values based on the field(s) specified in outFields.

Known Limitations

  • For service-based queries, this parameter applies only if the supportsAdvancedQueries capability of the layer is true.
  • Make sure to set returnGeometry to false when returnDistinctValues is true. Otherwise, reliable results will not be returned.
Default Value:false

spatialRelationship

Property
spatialRelationship String

For spatial queries, this parameter defines the spatial relationship to query features in the layer or layer view against the input geometry. The spatial relationships discover how features are spatially related to each other. For example, you may want to know if a polygon representing a county completely contains points representing settlements.

The spatial relationship is determined by whether the boundaries or interiors of a geometry intersect.

  • Boundary — The endpoints of all linear parts for line features, or the linear outline of a polygon. Only lines and polygons have boundaries.
  • Interior — Points are entirely interior and have no boundary. For lines and polygons, the interior is any part of the geometry that is not part of the boundary.

The possible values for this parameter are described below and the images highlight the geometries returned for the specified spatial relationship for given geometries.

The intersects spatial relationship returns features in the layer view that intersect the query geometry.

intersects

The contains spatial relationship returns features in the layer view that are completely contained by the query geometry.

contains

The crosses spatial relationship returns features in the layer view when the interior of a query geometry comes into contact with the interior or boundary of features in the layer view. In other words, the geometries share some interior area, but not all interior area.

crosses

The envelope-intersects spatial relationship returns features in the layer view that intersect the envelope (or extent) of the filter geometry.

envelope-intersects

The overlaps spatial relationship returns features in the layer view that overlap the query geometry. Only features of the same geometry can be compared.

overlaps

The touches spatial relationship returns features in the layer view that touch the query geometry. The boundaries of the geometries intersect, but not their interiors.

touches

The within spatial relationship returns features in the layer view that completely contain the query geometry. In other words, the filter geometry is completely within the features in the layer view. It is opposite of contains.

within

The disjoint spatial relationship returns features in the layer view that do not intersect the query geometry in anyway. Opposite of intersects.

disjoint

Known Limitations

  • For spatial queries on 3D Object SceneLayers and BuildingSceneLayers the spatial relationship is evaluated based on the Extent of the feature and not the footprint. This means that a feature might be returned from the query, even though its footprint is not in a spatial relationship with the geometry.
  • Currently only intersects, contains, and disjoint spatialRelationships are supported on spatial queries for 3D Object SceneLayers and BuildingSceneLayers.

Possible Values:"intersects" |"contains" |"crosses" |"disjoint" |"envelope-intersects" |"index-intersects" |"overlaps" |"touches" |"within" |"relation"

Default Value:intersects
Example
let query = new Query({
  spatialRelationship: "contains"
});

timeExtent

Property
timeExtent TimeExtent |null |undefinedautocast

A time extent for a temporal query against time-aware layers. For example, it can be used to discover all crimes that occurred during the night shift from 10 PM to 6 AM on a particular date.

Example
let layer = new FeatureLayer( ... );
let timeExtent = new TimeExtent({
  start: new Date(1992, 0, 1),
  end: new Date(1992, 11, 31)
});
let timeQuery = new Query({
  timeExtent: timeExtent
});
layerView.queryFeatures(timeQuery).then(function(featureSet) { ... });

units

Property
units String |null |undefined

The unit for calculating the buffer distance when distance is specified in spatial queries. If units 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 data spatial reference. For service-based queries, this parameter only applies if the layer's capabilities.query.supportsDistance is true.

Possible Values:"feet" |"miles" |"nautical-miles" |"us-nautical-miles" |"meters" |"kilometers"

Default Value:null
Example
// Query at a distance in pixels of the query geometry.
// Use the unit of the query geometry's spatial reference.
layerView.queryFeatures({
  geometry: event.mapPoint,
  distance: 2 * view.resolution,
  returnGeometry: true
}).then(processResults);

upperBoundaryAlias

Property
upperBoundaryAlias String |null |undefined

Sets the name of the upper boundary property in the response. By default, the upper boundary is name upperBoundary and indicates the value at the edge of each bin.

Default Value:null

where

Property
where String |null |undefined

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

Show inherited methods Hide inherited methods
Name Return Type Summary Class

Adds one or more handles which are to be tied to the lifecycle of the object.

Accessor

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product.

AttributeBinsQuery

Returns true if a named group of handles exist.

Accessor

Removes a group of handles owned by the object.

Accessor

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

AttributeBinsQuery

Method Details

addHandles

Inherited
Method
addHandles(handleOrHandles, groupKey)
Inherited from Accessor

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();
Parameters
handleOrHandles WatchHandle|WatchHandle[]

Handles marked for removal once the object is destroyed.

groupKey *
optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

fromJSON

Method
fromJSON(json){* |null |undefined}static

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameter
json Object

A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects.

Returns
Type Description
* | null | undefined Returns a new instance of this class.

hasHandles

Inherited
Method
hasHandles(groupKey){Boolean}
Inherited from Accessor

Returns true if a named group of handles exist.

Parameter
groupKey *
optional

A group key.

Returns
Type Description
Boolean Returns true if a named group of handles exist.
Example
// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

removeHandles

Inherited
Method
removeHandles(groupKey)
Inherited from Accessor

Removes a group of handles owned by the object.

Parameter
groupKey *
optional

A group key or an array or collection of group keys to remove.

Example
obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

toJSON

Method
toJSON(){Object}

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

Returns
Type Description
Object The ArcGIS portal JSON representation of an instance of this class.

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

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close