Skip to content
import StatisticDefinition from "@arcgis/core/rest/support/StatisticDefinition.js";
Inheritance:
StatisticDefinitionAccessor
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

Constructor

Constructor
Parameters
ParameterTypeDescriptionRequired
properties
See the properties table for a list of all the properties that may be passed into the constructor.

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.
PropertyTypeClass
declaredClass
readonly inherited
"count" | "sum" | "min" | "max" | "avg" | "stddev" | "var" | "exceedslimit" | "percentile-continuous" | "percentile-discrete" | "envelope-aggregate" | "centroid-aggregate" | "convex-hull-aggregate" | null | undefined

declaredClass

readonlyinherited Property
Type
string
Inherited from: Accessor
Since
ArcGIS Maps SDK for JavaScript 4.7

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

onStatisticField

Property
Type
string | null | undefined

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
Type
string | null | undefined

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
Type
PercentileParameters | null | undefined

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

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
Type
"count" | "sum" | "min" | "max" | "avg" | "stddev" | "var" | "exceedslimit" | "percentile-continuous" | "percentile-discrete" | "envelope-aggregate" | "centroid-aggregate" | "convex-hull-aggregate" | null | undefined

Defines the type of statistic.

Possible Values

ValueDescription
countThe number of features that match a specified criteria.
sumThe total sum of values that match a specified criteria.
minThe minimum value of a given field.
maxThe maximum value of a given field.
avgThe average of values that match a specified criteria.
stddevThe standard deviation of values that match a specified criteria.
varThe statistical variance of values in the specified criteria.
percentile-continuousAn 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-discreteSimilar to percentile-continuous except percentile-discrete returns a data value from a dataset.
envelope-aggregateReturns the spatial extent of grouped features when Query.groupByFieldsForStatistics is used. Each statistics group will have an extent representing the bounding box of all features in that group.
centroid-aggregateReturns the centroid of the grouped features when Query.groupByFieldsForStatistics is used. Each statistics group will have a centroid representing the spatial center of features belonging to the group.
convex-hull-aggregateReturns the convex hull of grouped features when Query.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 Query.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.

See also
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);
}
});
});

Methods

MethodSignatureClass
fromJSON
inherited static
fromJSON(json: any): any
clone(): StatisticDefinition
toJSON
inherited
toJSON(): any

fromJSON

inheritedstatic Method
Signature
fromJSON (json: any): any
Inherited from: JSONSupportMixin

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.

Parameters
ParameterTypeDescriptionRequired
json
any

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
any

Returns a new instance of this class.

clone

Method
Signature
clone (): StatisticDefinition

Creates a deep clone of StatisticDefinition object.

Returns
StatisticDefinition

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

toJSON

inherited Method
Signature
toJSON (): any
Inherited from: JSONSupportMixin

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

Returns
any

The ArcGIS portal JSON representation of an instance of this class.

Type definitions

PercentileParameters

Type definition

The parameters for percentile statistics.

See also

value

Property
Type
number

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

orderBy

Property
Type
"ASC" | "DESC" | undefined

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.