AggregationExecute

entityKey

Identifies the exact aggregation definition to execute.
This value must match a entityKey returned by aggregationCatalog.

• available filters
• allowed groupBy
• available valueColumns
• supported aggregationTypes

aggregationType

Defines the aggregation operation applied on valueColumn1 (for example: SUM, AVG, MIN, MAX, COUNT, DISTINCTCOUNT).
Supported values must match one of the aggregation types returned by aggregationCatalog.

• COUNT and DISTINCTCOUNT ignore valueColumn1
• DISTINCTCOUNT requires distinctCountName
• all sorting and Top N logic are always based on valueColumn1, even when valueColumn2 is provided

Grouping logic (groupByName × periodType)

The aggregation engine uses two independent grouping dimensions:

• a business dimension defined by groupByName
• a time dimension defined by periodType

These dimensions combine to determine the structure and number of rows returned. There are four possible combinations:

1. groupByName ≠ None and periodType ≠ None → one row per business entity and per period Example: revenue per customer, per month

2. groupByName ≠ None and periodType = None → one row per business entity, without time breakdown Example: total revenue per customer

3. groupByName = None and periodType ≠ None → one row per period, without business breakdown Example: global revenue per month

4. groupByName = None and periodType = None → a single grand total row, no grouping

periodType

Defines the time grouping granularity (for example: Day, Week, Month, Quarter, Year).
This value must match one of the period types returned by aggregationCatalog.

• when periodType ≠ None, results are grouped by period
• when periodType = None, no time grouping is applied and the provided dates are used as-is

groupByName

Defines the business grouping dimension (for example: Customer, Product, Account).
This value must match exactly one groupBy name returned by aggregationCatalog.

• when groupByName ≠ None, results are grouped by business entity
• when groupByName = None or empty, no business grouping is applied

When groupByName is set to None, the aggregation behaves as a pure time-series or grand-total aggregation.

• no entity ranking is performed
• date ranges are never recalculated
• top and compare only affect how results are interpreted, not which dates are selected

dateMin

dateMax

Define the reference date range for the aggregation.
Values must be provided as ISO 8601 date strings (for example 2024-01-01).
Dates are represented as strings because the aggregation engine accepts dynamic filter values rather than strongly typed GraphQL date parameters.

• When groupByName is set (not None or empty) and (top > 0 or compare = true) and periodType ≠ None:

  • dateMax is used as the reference date (fallback: dateMin, then today)
  • the engine automatically recalculates dateMin and dateMax to align with periodType
    • one period when using top
    • two periods (N and N-1) when using compare

• When groupByName = None or empty:

  • dateMin and dateMax are never recalculated
  • the engine returns all periods between dateMin and dateMax
  • when top or compare is used, dateMin is required

compare

When set to true and groupByName is set, the engine compares:

• the reference period (N)
• with the immediately preceding equivalent period (N-1)

This comparison is performed by periodType and per business entity (for example: by customer, month vs month-1).

• When groupByName is set, date recalculation rules apply (see dateMin/dateMax).
• When groupByName = None:
  • dates are not recalculated
  • the engine returns all periods between dateMin and dateMax

compare must not be used to compare business entities
(for example: “revenue per customer for June” is a breakdown, not a comparison).

The response structure changes to expose:

• periodN, periodN_1
• valueN, valueN_1
• deltaPercent

top

Defines how many groups are returned and how the result is ordered.

• -1 = No limit. All groups are returned without ranking
• 0 = All groups are returned, ordered by valueColumn1 descending

• > 0 = Only the Top N groups are returned, ordered by valueColumn1 descending

• When top > 0 and groupByName is set, the engine:
  • uses dateMax as the reference
  • recalculates the date range to one period aligned with periodType
• When groupByName = None:
  • dateMin and dateMax are used as-is
  • all periods between the two dates are returned

Sorting is always performed only on valueColumn1.

includeOthers

Used only when top > 0.
Adds an additional row that aggregates all remaining groups not included in the Top N.

othersLabel

Defines the label used for the aggregated row when includeOthers = true.
If not specified, the default value is Others.

filterName

Defines the business filter applied before aggregation.
This value must match exactly one filter name returned by aggregationCatalog.
This parameter selects business filters only (for example: “Validated invoices”, “Paid invoices”).

To restrict the aggregation to a specific entity (customer, product, supplier), use the search parameter instead.
When multiple ID types are supported, also provide searchScope.

valueColumn1

The main value used for the aggregation.
This value must match exactly one valueColumn name returned by aggregationCatalog.

• required unless aggregationType is COUNT or DISTINCTCOUNT
• used for all sorting and Top N logic

valueColumn2

Optional complementary value to valueColumn1.
This value must match exactly one valueColumn name returned by aggregationCatalog.

• returned as-is in the result
• never used for sorting or ranking

distinctCountName

Required only when aggregationType = DISTINCTCOUNT.
This value must match one of the distinctCount values returned by aggregationCatalog.

search

Optional parameter used to restrict the aggregation to a specific entity identifier
(for example: customer id, product id, supplier id).
This restriction is applied on top of the selected filterName.

searchScope

Optional parameter used when the aggregation supports multiple ID types.
Supported values are exposed by searchScopes returned by aggregationCatalog

When only one searchScope is available, this parameter can be omitted.