StatisticDefinition

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

This class defines the parameters for querying a layer or layer view for statistics.

See also
Examples
// query for the sum of the population in all features
let sumPopulation = {
  onStatisticField: "POP_2015",  // service field for 2015 population
  outStatisticFieldName: "Pop_2015_sum",
  statisticType: "sum"
}
let query = layer.createQuery();
query.outStatistics = [ sumPopulation ];
layer.queryFeatures(query)
  .then(function(response){
     let stats = response.features[0].attributes;
     console.log("output stats:", stats);
  });
// query for the average of the population change for all features
let populationChangeDefinition = {
  onStatisticField: "POP_2015 - POP_2010",  // service field for 2015 population
  outStatisticFieldName: "avg_pop_change_2015_2010",
  statisticType: "avg"
}
let query = layer.createQuery();
query.outStatistics = [ populationChangeDefinition ];
layer.queryFeatures(query)
  .then(function(response){
     let stats = response.features[0].attributes;
     console.log("Average change:", stats.avg_pop_change_2015_2010);
  });

Constructors

StatisticDefinition

Constructor
new StatisticDefinition(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.
Show inherited properties Hide inherited properties
Name Type Summary Class
String

The name of the class.

Accessor
String

Defines the field for which statistics will be calculated.

StatisticDefinition
String

Specifies the output field name for the requested statistic.

StatisticDefinition
Object

The parameters for percentile statistics.

StatisticDefinition
String

Defines the type of statistic.

StatisticDefinition

Property Details

declaredClass

Inherited
Property
declaredClass Stringreadonly
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.7 Accessor since 4.0, declaredClass added at 4.7.

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

onStatisticField

Property
onStatisticField String

Defines the field for which statistics will be calculated. This can be service field names or SQL expressions. See the snippets below for examples.

Examples
// query for the sum of the population in all features
let sumPopulation = {
  onStatisticField: "POP_2015",  // service field for 2015 population
  outStatisticFieldName: "Pop_2015_sum",
  statisticType: "sum"
}
let query = layer.createQuery();
query.outStatistics = [ sumPopulation ];
layer.queryFeatures(query)
  .then(function(response){
     let stats = response.features[0].attributes;
     console.log("output stats:", stats);
  });
// query for the average of the population change for all features
// Notice that you can pass a SQL expression as a field name to calculate statistics
let populationChangeDefinition = {
  onStatisticField: "POP_2015 - POP_2010",  // service field for 2015 population
  outStatisticFieldName: "avg_pop_change_2015_2010",
  statisticType: "avg"
}
let query = layer.createQuery();
query.outStatistics = [ populationChangeDefinition ];
layer.queryFeatures(query)
  .then(function(response){
     let stats = response.features[0].attributes;
     console.log("Average change:", stats.avg_pop_change_2015_2010);
  });
// query for the average of the population change grouped by regions
// query result will also return an extent for each group encompassing
// all features in each group.
let populationChangeDefinition = {
  onStatisticField: "POP_2015 - POP_2010",  // service field for 2015 population
  outStatisticFieldName: "avg_pop_change_2015_2010",
  statisticType: "avg"
};
let aggregatedExtent = {
  statisticType: "envelope-aggregate"
};
let query = layer.createQuery();
query.groupByFieldsForStatistics = ["Region"];
query.outStatistics = [ populationChangeDefinition, aggregatedExtent ];
layer.queryFeatures(query).then(displayResults);

outStatisticFieldName

Property
outStatisticFieldName String

Specifies the output field name for the requested statistic. Output field names can only contain alpha-numeric characters and an underscore. If no output field name is specified, the server assigns a field name to the returned statistic field.

statisticParameters

Property
statisticParameters Object

The parameters for percentile statistics. This property must be set when the statisticType is set to either percentile-continuous or percentile-discrete.

Properties
value Number

Percentile value. This should be a decimal value between 0 and 1.

orderBy String
optional

Specify ASC (ascending) or DESC (descending) to control the order of the data. For example, in a data set of 10 values from 1 to 10, the percentile value for 0.9 with orderBy set to ascending (ASC) is 9, but when orderBy is set to descending (DESC) the result is 2. The default is ASC.

Possible Values:"ASC"|"DESC"

Default Value:null
Examples
let query = layer.createQuery();
// find the median value in descending order for response_rate field
// for all features stored in the layer and order
query.outStatistics = [{
  statisticType: "percentile-continuous",
  statisticParameters: {
    value: 0.5,
    orderBy: "DESC"
  },
  onStatisticField: "response_rate",
  outStatisticFieldName: "Resp_rate_median"
}];
// query the features for the median value statistics against the values
// stored in the response_rate field
queryFeatures(query);
// Query the percentile for response time in descending order for all features in the layer
// group the percentile by Division and unit fields
let query = layer.createQuery();
query.orderByFields = ["Division, Unit"];
query.groupByFieldsForStatistics = ["Division, Unit"];
query.outStatistics = [{
  statisticType: "percentile-discrete",
  statisticParameters: {
    value: 0.67,
    orderBy: "DESC"
  },
  onStatisticField: "response_time",
  outStatisticFieldName: "response_time_percentile"
}];
queryFeatures(query);

statisticType

Property
statisticType String

Defines the type of statistic.

Possible Values

Value Description
count The number of features that match a specified criteria.
sum The total sum of values that match a specified criteria.
min The minimum value of a given field.
max The maximum value of a given field.
avg The average of values that match a specified criteria.
stddev The standard deviation of values that match a specified criteria.
var The statistical variance of values in the specified criteria.
percentile-continuous An interpolated value above or below which a given percentage of values in a group of data lie. For example, the 90th percentile (value 0.9) is the value below which 90% of the data values may be found. percentile-continuous returns an interpolated value from the dataset.
percentile-discrete Similar to percentile-continuous except percentile-discrete returns a data value from a dataset.
envelope-aggregate Returns the spatial extent of grouped features when groupByFieldsForStatistics is used. Each statistics group will have an extent representing the bounding box of all features in that group.
centroid-aggregate Returns the centroid of the grouped features when groupByFieldsForStatistics is used. Each statistics group will have a centroid representing the spatial center of features belonging to the group.
convex-hull-aggregate Returns the convex hull of grouped features when groupByFieldsForStatistics is used. Each statistics group will have a convex hull representing the smallest area containing all features in that group.

Known Limitations

  • The statisticParameters must be set when calculating percentile-continuous or percentile-discrete statistics.
  • The percentile-continuous and percentile-discrete statistic types cannot be used with the having parameter.
  • The percentile-continuous and percentile-discrete statistic types are supported if capabilities.query.supportsPercentileStatistics is true.
  • The envelope-aggregate, centroid-aggregate and convex-hull-aggregate statistic types are not supported with ArcGIS Enterprise hosted and non-hosted feature services.

Possible Values:"count"|"sum"|"min"|"max"|"avg"|"stddev"|"var"|"percentile-continuous"|"percentile-discrete"|"envelope-aggregate"|"centroid-aggregate"|"convex-hull-aggregate"

Example
// average of age fields by regions
const ageStatsByRegion = new StatisticDefinition({
  onStatisticField: field,
  outStatisticFieldName: "avgAge",
  statisticType: "avg"
});

// extent encompassing all features by region
const aggregatedExtent = new StatisticDefinition({
  statisticType: "envelope-aggregate",
  outStatisticFieldName: "aggregateExtent",
});

// group the statistics by Region field
// get avg age by Regions and extent of each region
const query = layer.createQuery();
query.groupByFieldsForStatistics = ["Region"];
query.outStatistics = [consumeStatsByRegion, aggregatedExtent];
layer.queryFeatures(query).then((results) => {
  results.features.forEach((feature) => {
    if (feature.attributes.Region === "Midwest") {
       view.goTo(feature.aggregateGeometries.aggregateExtent);
    }
  });
});

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
StatisticDefinition

Creates a deep clone of StatisticDefinition object.

StatisticDefinition
*

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

StatisticDefinition
Boolean

Returns true if a named group of handles exist.

Accessor

Removes a group of handles owned by the object.

Accessor
Object

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

StatisticDefinition

Method Details

addHandles

Inherited
Method
addHandles(handleOrHandles, groupKey)
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, addHandles added at 4.25.

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.

clone

Method
clone(){StatisticDefinition}

Creates a deep clone of StatisticDefinition object.

Returns
Type Description
StatisticDefinition A new instance of a StatisticDefinition object equal to the object used to call .clone().

fromJSON

Method
fromJSON(json){*}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
* Returns a new instance of this class.

hasHandles

Inherited
Method
hasHandles(groupKey){Boolean}
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, hasHandles added at 4.25.

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
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, removeHandles added at 4.25.

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.