@arcgis/core/rest/support/AttributeBinsQuery.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type SpatialReference from "../../geometry/SpatialReference.js";
import type AutoIntervalBinParameters from "./AutoIntervalBinParameters.js";
import type DateBinParameters from "./DateBinParameters.js";
import type FixedBoundariesBinParameters from "./FixedBoundariesBinParameters.js";
import type FixedIntervalBinParameters from "./FixedIntervalBinParameters.js";
import type StatisticDefinition from "./StatisticDefinition.js";
import type TimeExtent from "../../time/TimeExtent.js";
import type { ClonableMixin } from "../../core/Clonable.js";
import type { JSONSupport } from "../../core/JSONSupport.js";
import type { GeometryWithoutMeshUnion } from "../../geometry/types.js";
import type { DatumTransformation } from "../../portal/jsonTypes.js";
import type { IANATimeZone } from "../../time/types.js";
import type { FixedIntervalBinParametersProperties } from "./FixedIntervalBinParameters.js";
import type { FixedBoundariesBinParametersProperties } from "./FixedBoundariesBinParameters.js";
import type { DateBinParametersProperties } from "./DateBinParameters.js";
import type { AutoIntervalBinParametersProperties } from "./AutoIntervalBinParameters.js";
import type { PolylineProperties } from "../../geometry/Polyline.js";
import type { PolygonProperties } from "../../geometry/Polygon.js";
import type { PointProperties } from "../../geometry/Point.js";
import type { MultipointProperties } from "../../geometry/Multipoint.js";
import type { ExtentProperties } from "../../geometry/Extent.js";
import type { SpatialReferenceProperties } from "../../geometry/SpatialReference.js";
import type { StatisticDefinitionProperties } from "./StatisticDefinition.js";
import type { TimeExtentProperties } from "../../time/TimeExtent.js";

export interface AttributeBinsQueryProperties extends Partial<Pick<AttributeBinsQuery, "binOrder" | "cacheHint" | "datumTransformation" | "distance" | "lowerBoundaryAlias" | "outTimeZone" | "returnDistinctValues" | "spatialRelationship" | "units" | "upperBoundaryAlias" | "where">> {
  /**
   * 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.
   */
  binParameters?: ((AutoIntervalBinParametersProperties & { type: "auto-interval" }) | (DateBinParametersProperties & { type: "date" }) | (FixedBoundariesBinParametersProperties & { type: "fixed-boundaries" }) | (FixedIntervalBinParametersProperties & { type: "fixed-interval" }));
  /**
   * The geometry to apply to the spatial filter. The [Query.spatialRelationship](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#spatialRelationship)
   * will indicate how the geometry should be used to query features.
   *
   * > [!WARNING]
   * >
   * > **Known Limitations**
   * >
   * > [Mesh](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/) geometry types are currently not supported.
   */
  geometry?: ((ExtentProperties & { type: "extent" }) | (MultipointProperties & { type: "multipoint" }) | (PointProperties & { type: "point" }) | (PolygonProperties & { type: "polygon" }) | (PolylineProperties & { type: "polyline" })) | null;
  /**
   * The spatial reference for the returned geometry. If not specified, the geometry is returned in the spatial
   * reference of the queried layer.
   */
  outSpatialReference?: SpatialReferenceProperties | null;
  /**
   * The definitions for one or more field-based statistics to be calculated. For service-based queries, check the layer's
   * [query.queryAttributeBins.supportedStatistics](https://developers.arcgis.com/javascript/latest/references/core/layers/types/#FeatureLayerCapabilities) 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]
   * });
   */
  outStatistics?: StatisticDefinitionProperties[] | null;
  /**
   * A time extent for a temporal query against [time-aware layers](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#timeInfo).
   * 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) { ... });
   */
  timeExtent?: TimeExtentProperties | null;
}

/**
 * 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.
 *
 * @see [binParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AttributeBinsQuery/#binParameters)
 */
export type BinParameters = AutoIntervalBinParameters | DateBinParameters | FixedBoundariesBinParameters | FixedIntervalBinParameters;

/**
 * This class configures parameters for the [queryAttributeBins](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#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](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AttributeBinsQuery/#binParameters) property defines bin characteristics like size and start value, while the [outStatistics](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AttributeBinsQuery/#outStatistics) parameter specifies the information each bin provides.
 * Features can be filtered using a [where](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AttributeBinsQuery/#where) condition and a [spatial filter](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AttributeBinsQuery/#geometry). 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](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AutoIntervalBinParameters/) | You specify the number of [numBins](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AutoIntervalBinParameters/#numBins), [start](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AutoIntervalBinParameters/#start) and [end](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AutoIntervalBinParameters/#end) values of the binning. The bin size is calculated by dividing the dataset's range by this number of bins.|
 * | [FixedBoundariesBinParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FixedBoundariesBinParameters/) | The bins strictly follow the specified [input values](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FixedBoundariesBinParameters/#boundaries). 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](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FixedIntervalBinParameters/) | The number of bins is not important, but the [interval](https://developers.arcgis.com/javascript/latest/references/core/rest/support/FixedIntervalBinParameters/#interval) size must match the input data. Each bin will cover a range that exactly fits the specified interval. |
 * | [DateBinParameters](https://developers.arcgis.com/javascript/latest/references/core/rest/support/DateBinParameters/) | The [intervals](https://developers.arcgis.com/javascript/latest/references/core/rest/support/DateBinParameters/#interval) are based on calendar units. For example, with monthly intervals, each bin represents an entire month. |
 *
 * @since 4.32
 * @see [FeatureLayer.queryAttributeBins()](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#queryAttributeBins)
 * @see [Sample - Attribute Bins Query](https://developers.arcgis.com/javascript/latest/sample-code/query-attribute-bins/)
 */
export default class AttributeBinsQuery extends AttributeBinsQuerySuperclass {
  constructor(properties?: AttributeBinsQueryProperties);
  /**
   * Bins can be returned in ascending or descending order. The default is `ascending`.
   *
   * @default "ascending"
   */
  binOrder?: "ascending" | "descending" | null;
  /**
   * 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.
   */
  get binParameters(): BinParameters;
  set binParameters(value: ((AutoIntervalBinParametersProperties & { type: "auto-interval" }) | (DateBinParametersProperties & { type: "date" }) | (FixedBoundariesBinParametersProperties & { type: "fixed-boundaries" }) | (FixedIntervalBinParametersProperties & { type: "fixed-interval" })));
  /**
   * Indicates if the service should cache the query results. It only applies if the layer's
   * [capabilities.query.supportsCacheHint](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#capabilities) is set to `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](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#outStatistics) or [features](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#returnGeometry) on app load.
   * * Queries based on [preset input](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#where), for example, a drop-down list of US states.
   * * Queries based on [preset extents](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry), for example bookmarks, in web maps.
   */
  accessor cacheHint: boolean | null | undefined;
  /**
   * Datum transformation used for projecting geometries in the query results when
   * [outSpatialReference](https://developers.arcgis.com/javascript/latest/references/core/rest/support/AttributeBinsQuery/#outSpatialReference) is different than the layer's spatial reference.
   * Requires ArcGIS Server service 10.5 or greater.
   */
  accessor datumTransformation: DatumTransformation | null | undefined;
  /**
   * Specifies a search distance from a given [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry) in a spatial query.
   * The [units property](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#units) indicates the unit of measurement. In essence, setting this property
   * creates a buffer at the specified size around the input [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#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](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#spatialRelationship).
   *
   * If querying a feature service, the [supportsQueryWithDistance](https://developers.arcgis.com/rest/services-reference/query-feature-service-layer-.htm)
   * capability must be `true`.
   */
  accessor distance: number | null | undefined;
  /**
   * The geometry to apply to the spatial filter. The [Query.spatialRelationship](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#spatialRelationship)
   * will indicate how the geometry should be used to query features.
   *
   * > [!WARNING]
   * >
   * > **Known Limitations**
   * >
   * > [Mesh](https://developers.arcgis.com/javascript/latest/references/core/geometry/Mesh/) geometry types are currently not supported.
   */
  get geometry(): GeometryWithoutMeshUnion | null | undefined;
  set geometry(value: ((ExtentProperties & { type: "extent" }) | (MultipointProperties & { type: "multipoint" }) | (PointProperties & { type: "point" }) | (PolygonProperties & { type: "polygon" }) | (PolylineProperties & { type: "polyline" })) | 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. */
  accessor lowerBoundaryAlias: string | null | undefined;
  /**
   * The spatial reference for the returned geometry. If not specified, the geometry is returned in the spatial
   * reference of the queried layer.
   */
  get outSpatialReference(): SpatialReference | null;
  set outSpatialReference(value: SpatialReferenceProperties | null);
  /**
   * The definitions for one or more field-based statistics to be calculated. For service-based queries, check the layer's
   * [query.queryAttributeBins.supportedStatistics](https://developers.arcgis.com/javascript/latest/references/core/layers/types/#FeatureLayerCapabilities) 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]
   * });
   */
  get outStatistics(): StatisticDefinition[] | null | undefined;
  set outStatistics(value: StatisticDefinitionProperties[] | null | undefined);
  /**
   * Defines the [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) 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.
   *
   * @see [wikipedia - List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
   * @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
   * });
   */
  accessor outTimeZone: IANATimeZone | null | undefined;
  /**
   * If `true`, all aggregations apply on distinct values.
   *
   * @default false
   */
  accessor returnDistinctValues: boolean | null | undefined;
  /**
   * For spatial queries, this parameter defines the spatial relationship to query features in the layer or layer view against the input [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#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 [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry).
   *
   * ![intersects](https://developers.arcgis.com/javascript/latest/assets/img/apiref/layers/spatialRelationships/intersects.png)
   *
   * The `contains` spatial relationship returns features in the layer view that are completely contained by the query [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry).
   *
   * ![contains](https://developers.arcgis.com/javascript/latest/assets/img/apiref/layers/spatialRelationships/contains.png)
   *
   * The `crosses` spatial relationship returns features in the layer view when the interior of a query [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/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](https://developers.arcgis.com/javascript/latest/assets/img/apiref/layers/spatialRelationships/crosses.png)
   *
   * The `envelope-intersects` spatial relationship returns features in the layer view that intersect the envelope (or extent)
   * of the filter [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry).
   *
   * ![envelope-intersects](https://developers.arcgis.com/javascript/latest/assets/img/apiref/layers/spatialRelationships/envelope-intersects.png)
   *
   * The `overlaps` spatial relationship returns features in the layer view that overlap the query [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry).
   * Only features of the same geometry can be compared.
   *
   * ![overlaps](https://developers.arcgis.com/javascript/latest/assets/img/apiref/layers/spatialRelationships/overlap.png)
   *
   * The `touches` spatial relationship returns features in the layer view that touch the query [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry).
   * The boundaries of the geometries intersect, but not their interiors.
   *
   * ![touches](https://developers.arcgis.com/javascript/latest/assets/img/apiref/layers/spatialRelationships/touches.png)
   *
   * The `within` spatial relationship returns features in the layer view that completely contain the query [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry).
   * In other words, the filter geometry is completely `within` the features in the layer view. It is opposite of
   * `contains`.
   *
   * ![within](https://developers.arcgis.com/javascript/latest/assets/img/apiref/layers/spatialRelationships/within.png)
   *
   * The `disjoint` spatial relationship returns features in the layer view that do not intersect the query [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry) in anyway.
   * Opposite of `intersects`.
   *
   * ![disjoint](https://developers.arcgis.com/javascript/latest/assets/img/apiref/layers/spatialRelationships/disjoint.png)
   *
   * > [!WARNING]
   * >
   * > **Known Limitations**
   * >
   * > For spatial queries on 3D Object SceneLayers and BuildingSceneLayers the spatial relationship is evaluated based on the
   * > [Extent](https://developers.arcgis.com/javascript/latest/references/core/geometry/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 [Query.geometry](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#geometry).
   * > Currently only `intersects`, `contains`, and `disjoint` [spatialRelationships](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#spatialRelationship) are supported on spatial
   * > [queries](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/) for 3D Object SceneLayers and BuildingSceneLayers.
   *
   * @default "intersects"
   * @default intersects
   * @example
   * let query = new Query({
   *   spatialRelationship: "contains"
   * });
   */
  spatialRelationship: "intersects" | "contains" | "crosses" | "disjoint" | "envelope-intersects" | "index-intersects" | "overlaps" | "touches" | "within" | "relation";
  /**
   * A time extent for a temporal query against [time-aware layers](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#timeInfo).
   * 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) { ... });
   */
  get timeExtent(): TimeExtent | null | undefined;
  set timeExtent(value: TimeExtentProperties | null | undefined);
  /**
   * The unit for calculating the buffer distance when [Query.distance](https://developers.arcgis.com/javascript/latest/references/core/rest/support/Query/#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](https://developers.arcgis.com/javascript/latest/references/core/layers/FeatureLayer/#capabilities) is `true`.
   *
   * @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);
   */
  accessor units: "feet" | "miles" | "nautical-miles" | "us-nautical-miles" | "meters" | "kilometers" | 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. */
  accessor upperBoundaryAlias: 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.
   *
   * @default "1=1"
   * @example query.where = "NAME = '" + stateName + "'";
   * @example query.where = "POP04 > " + population;
   */
  accessor where: string | null | undefined;
}
declare const AttributeBinsQuerySuperclass: typeof JSONSupport & typeof ClonableMixin