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.

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
name: str
supportedTypes: Set[QMetaType.Type]
class AggregateParameters

Bases: object

A bundle of parameters controlling aggregate calculation

delimiter: str
filter: str
orderBy: OrderBy
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