Class: QgsAggregateCalculator

Utility class for calculating aggregates for a field (or expression) over the features from a vector layer.

Note

It is recommended that QgsVectorLayer.aggregate() is used rather then directly using this class, as the QgsVectorLayer method can handle delegating aggregate calculation to a data provider for remote calculation.

Enums

Aggregate

Available aggregates to calculate.

Methods

calculate

Calculates the value of an aggregate.

delimiter

Returns the delimiter used for joining values with the StringConcatenate aggregate.

filter

Returns the filter which limits the features used during the aggregate calculation.

lastError

Returns the last error encountered during the aggregate calculation.

layer

Returns the associated vector layer.

setDelimiter

Sets the delimiter to use for joining values with the StringConcatenate aggregate.

setFidsFilter

Sets a filter to limit the features used during the aggregate calculation.

setFilter

Sets a filter to limit the features used during the aggregate calculation.

setParameters

Sets all aggregate parameters from a parameter bundle.

Static Methods

aggregates

Structured information for available aggregates.

displayName

Returns the friendly display name for a aggregate.

stringToAggregate

Converts a string to a aggregate type.
class qgis.core.QgsAggregateCalculator[source]

Bases: object

__init__(layer: QgsVectorLayer | None)

Constructor for QgsAggregateCalculator.

Parameters:

layer (Optional[QgsVectorLayer]) – vector layer to calculate aggregate from

__init__(a0: QgsAggregateCalculator)
Parameters:

a0 (QgsAggregateCalculator)

class Aggregate(*values)

Bases: IntEnum

Available aggregates to calculate. Not all aggregates are available for all field types.

Added in version 3.36..

  • Count: Count

  • CountDistinct: Number of distinct values

  • CountMissing: Number of missing (null) values

  • Min: Min of values

  • Max: Max of values

  • Sum: Sum of values

  • Mean: Mean of values (numeric fields only)

  • Median: Median of values (numeric fields only)

  • StDev: Standard deviation of values (numeric fields only)

  • StDevSample: Sample standard deviation of values (numeric fields only)

  • Range: Range of values (max - min) (numeric and datetime fields only)

  • Minority: Minority of values

  • Majority: Majority of values

  • FirstQuartile: First quartile (numeric fields only)

  • ThirdQuartile: Third quartile (numeric fields only)

  • InterQuartileRange: Inter quartile range (IQR) (numeric fields only)

  • StringMinimumLength: Minimum length of string (string fields only)

  • StringMaximumLength: Maximum length of string (string fields only)

  • StringConcatenate: Concatenate values with a joining string (string fields only). Specify the delimiter using setDelimiter().

  • GeometryCollect: Create a multipart geometry from aggregated geometries

  • ArrayAggregate: Create an array of values

  • StringConcatenateUnique: Concatenate unique values with a joining string (string fields only). Specify the delimiter using setDelimiter().

class AggregateInfo

Bases: object

Structured information about the available aggregates.

function: str

The expression function

name: str

A translated, human readable name

supportedTypes: Set[QMetaType.Type]

This aggregate function can only be used with these datatypes

class AggregateParameters

Bases: object

A bundle of parameters controlling aggregate calculation

delimiter: str

Delimiter to use for joining values with the StringConcatenate aggregate.

See also

QgsAggregateCalculator.setDelimiter()

See also

QgsAggregateCalculator.delimiter()

filter: str

Optional filter for calculating aggregate over a subset of features, or an empty string to use all features.

See also

QgsAggregateCalculator.setFilter()

See also

QgsAggregateCalculator.filter()

orderBy: OrderBy

Optional order by clauses.

Added in version 3.8.

static aggregates() → List[QgsAggregateCalculator.AggregateInfo]

Structured information for available aggregates.

Added in version 3.2.

Return type:

List[QgsAggregateCalculator.AggregateInfo]

calculate(self, aggregate: Qgis.Aggregate, fieldOrExpression: str | None, context: QgsExpressionContext | None = None, feedback: QgsFeedback | None = None)[source]

Calculates the value of an aggregate.

Parameters:

  • aggregate (Qgis.Aggregate) – aggregate to calculate

  • fieldOrExpression (Optional[str]) – source field or expression to use as basis for aggregated values. If an expression is used, then the context parameter must be set.

  • context (Optional[QgsExpressionContext] = None) – expression context for evaluating expressions

  • ok – if specified, will be set to True if aggregate calculation was successful. If ok is False then lastError() can be used to retrieve a descriptive error message.

  • feedback (Optional[QgsFeedback] = None) -> (Any) – optional feedback argument for early cancellation (since QGIS 3.22). If set, this will take precedence over any feedback object set on the expression context.

Returns:

calculated aggregate value

delimiter(self) → str[source]

Returns the delimiter used for joining values with the StringConcatenate aggregate.

See also

setDelimiter()

Return type:

str

static displayName(aggregate: Qgis.Aggregate) → str[source]

Returns the friendly display name for a aggregate.

Added in version 3.22.

Parameters:

aggregate (Qgis.Aggregate)

Return type:

str

filter(self) → str[source]

Returns the filter which limits the features used during the aggregate calculation.

See also

setFilter()

Return type:

str

lastError(self) → str[source]

Returns the last error encountered during the aggregate calculation.

Added in version 3.22.

Return type:

str

layer(self) → QgsVectorLayer | None[source]

Returns the associated vector layer.

Return type:

Optional[QgsVectorLayer]

setDelimiter(self, delimiter: str | None)[source]

Sets the delimiter to use for joining values with the StringConcatenate aggregate.

Parameters:

delimiter (Optional[str]) – string delimiter

See also

delimiter()

setFidsFilter(self, fids: Any)[source]

Sets a filter to limit the features used during the aggregate calculation. If an expression filter is set, it will override this filter.

Parameters:

fids (Any) – feature ids for feature filtering, and empty list will return no features.

See also

filter()

setFilter(self, filterExpression: str | None)[source]

Sets a filter to limit the features used during the aggregate calculation.

Parameters:

filterExpression (Optional[str]) – expression for filtering features, or empty string to remove filter

See also

filter()

setParameters(self, parameters: QgsAggregateCalculator.AggregateParameters)[source]

Sets all aggregate parameters from a parameter bundle.

Parameters:

parameters (QgsAggregateCalculator.AggregateParameters) – aggregate parameters

static stringToAggregate(string: str | None)[source]

Converts a string to a aggregate type.

Parameters:

  • string (Optional[str]) -> (Qgis.Aggregate) – string to convert

  • ok – if specified, will be set to True if conversion was successful

Returns:

aggregate type