# Aggregate

relationalai.semantics.frontend.base

```python
Aggregate(op: Relationship, *args: Value | Distinct, distinct: bool = False)
```

Represents an aggregate computation in the DSL.

`Aggregate` objects are returned by aggregate helpers such as
`count` and `sum`.
Use [`Aggregate.per`](/api/python/v2.2/semantics/frontend/base/aggregate_class/index.md#method-per) to add grouping keys (like SQL `GROUP BY`) and
[`Aggregate.where`](/api/python/v2.2/semantics/frontend/base/aggregate_class/index.md#method-where) to restrict which bindings contribute to the aggregate.

To aggregate over unique values, wrap arguments with
[`Model.distinct`](/api/python/v2.2/semantics/frontend/base/model_class/index.md#method-distinct) (or [`distinct`](/api/python/v2.2/semantics/distinct/index.md)).

## Parameters

- `op` ([`Relationship`](/api/python/v2.2/semantics/frontend/base/relationship_class/index.md)) - The aggregate operator (typically created by the standard aggregate helpers).
- `*args` ([`Value`](/api/python/v2.2/semantics/frontend/base/value/index.md) | [`Distinct`](/api/python/v2.2/semantics/frontend/base/distinct_class/index.md), default: `()`) - Values to aggregate. Pass a single [`Distinct`](/api/python/v2.2/semantics/frontend/base/distinct_class/index.md) to aggregate over unique values.
- `distinct` (`bool`, default: `False`) - If True, treat the aggregate as distinct.

## Notes

Most users should not instantiate this class directly.

## Methods

### .`where`()

```python
Aggregate.where(*args: Statement) -> Aggregate
```

Return a new aggregate restricted to bindings that satisfy the given
conditions.

This behaves like filtering *inside* the aggregate: only matches that
satisfy the conditions contribute to the aggregate result. (It does not
filter the rows of the surrounding query; use [`Fragment.where`](/api/python/v2.2/semantics/frontend/base/fragment_class/index.md#method-where) for that.)

**Parameters:**

- `*args` ([`Statement`](/api/python/v2.2/semantics/frontend/base/statement/index.md), default: `()`) - One or more [`semantics.frontend.base.Statement`](/api/python/v2.2/semantics/frontend/base/statement/index.md) items to use as filter conditions.

**Returns:**

- [`Aggregate`](/api/python/v2.2/semantics/frontend/base/aggregate_class/index.md) - A new aggregate with the additional filter(s) applied.

**Examples:**

Count only employees older than 30 per department:

```python
from relationalai.semantics import Integer, Model, count

m = Model()
Department = m.Concept("Department")
Employee = m.Concept("Employee")
Employee.age = m.Property(f"{Employee} is {Integer:age} years old")
Department.employees = m.Relationship(f"{Department} has {Employee:employees}")
employees = Department.employees
count(employees).per(Department).where(employees.age > 30)
```

### .`per`()

```python
Aggregate.per(*args: Value) -> Aggregate
```

Return a new aggregate grouped by the given key(s).

This behaves like adding SQL `GROUP BY` keys: the aggregate is
computed separately for each unique combination of the grouping values.

**Parameters:**

- `*args` ([`Value`](/api/python/v2.2/semantics/frontend/base/value/index.md), default: `()`) - One or more values to group by.

**Returns:**

- [`Aggregate`](/api/python/v2.2/semantics/frontend/base/aggregate_class/index.md) - A new aggregate with the additional grouping key(s) applied.

**Examples:**

Count employees per department:

```python
from relationalai.semantics import Model, count

m = Model()
Department = m.Concept("Department")
Employee = m.Concept("Employee")
Department.employees = m.Relationship(f"{Department} has {Employee:employees}")
count(Department.employees).per(Department)
```

**Notes:**

A value-typed key (a String, Date, Boolean or a number) has to be given
values somewhere in its scope. An entity key needs no binding -- its
Concept supplies the groups -- but a value-typed one has no such list,
so grouping by one that nothing binds is refused: give it values with a
`.where(...)`, or drop it from the grouping.

**Referenced By:**

1. [RelationalAI Documentation](/index.md)1) [Build With RelationalAI](/build/index.md)1. [Use advanced reasoning](/build/reasoning/index.md) / [Prescriptive reasoning](/build/reasoning/prescriptive/index.md) / [Solve a decision problem](/build/reasoning/prescriptive/decision-problems/index.md)1) [Add constraints](/build/reasoning/prescriptive/decision-problems/constraints/index.md)1. [Use common constraint patterns](/build/reasoning/prescriptive/decision-problems/constraints/index.md#use-common-constraint-patterns)

## Inheritance Hierarchy

```d2 inline layout=dagre theme=0 darkTheme=false pad=8 title="Inheritance hierarchy"
direction: down
"relationalai.semantics.frontend.base.Aggregate": {
  label: "Aggregate"
  link: "/api/python/v2.2/semantics/frontend/base/aggregate_class"
}
"relationalai.semantics.frontend.base.Variable": {
  label: "Variable"
  link: "/api/python/v2.2/semantics/frontend/base/variable_class"
}
"relationalai.semantics.frontend.base.DSLBase": {
  label: "DSLBase"
  link: "/api/python/v2.2/semantics/frontend/base/dslbase_class"
}
"relationalai.semantics.frontend.base.Variable" -> "relationalai.semantics.frontend.base.Aggregate"
"relationalai.semantics.frontend.base.DSLBase" -> "relationalai.semantics.frontend.base.Variable"
```

## Used By

1. [semantics](/api/python/v2.2/semantics/index.md) / [frontend](/api/python/v2.2/semantics/frontend/index.md) / [base](/api/python/v2.2/semantics/frontend/base/index.md)1) [Statement](/api/python/v2.2/semantics/frontend/base/statement/index.md)

## Returned By

1. [semantics](/api/python/v2.2/semantics/index.md)1) [frontend](/api/python/v2.2/semantics/frontend/index.md) / [base](/api/python/v2.2/semantics/frontend/base/index.md)1. [Aggregate](/api/python/v2.2/semantics/frontend/base/aggregate_class/index.md)1) [per](/api/python/v2.2/semantics/frontend/base/aggregate_class/index.md#method-per)
         2) [where](/api/python/v2.2/semantics/frontend/base/aggregate_class/index.md#method-where)
   2) [std](/api/python/v2.2/semantics/std/index.md) / [aggregates](/api/python/v2.2/semantics/std/aggregates/index.md)1) [Per](/api/python/v2.2/semantics/std/aggregates/per_class/index.md)1. [avg](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-avg)
         2. [bottom](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-bottom)
         3. [count](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-count)
         4. [cumsum\_asc](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-cumsum_asc)
         5. [limit](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-limit)
         6. [max](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-max)
         7. [median](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-median)
         8. [min](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-min)
         9. [percentile](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-percentile)
         10. [product](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-product)
         11. [rank](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-rank)
         12. [rank\_asc](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-rank_asc)
         13. [rank\_desc](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-rank_desc)
         14. [string\_join](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-string_join)
         15. [sum](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-sum)
         16. [top](/api/python/v2.2/semantics/std/aggregates/per_class/index.md#method-top)
      2) [avg](/api/python/v2.2/semantics/std/aggregates/avg/index.md)
      3) [bottom](/api/python/v2.2/semantics/std/aggregates/bottom/index.md)
      4) [count](/api/python/v2.2/semantics/std/aggregates/count/index.md)
      5) [cumsum\_asc](/api/python/v2.2/semantics/std/aggregates/cumsum_asc/index.md)
      6) [geometric\_mean](/api/python/v2.2/semantics/std/aggregates/geometric_mean/index.md)
      7) [limit](/api/python/v2.2/semantics/std/aggregates/limit/index.md)
      8) [max](/api/python/v2.2/semantics/std/aggregates/max/index.md)
      9) [median](/api/python/v2.2/semantics/std/aggregates/median/index.md)
      10) [min](/api/python/v2.2/semantics/std/aggregates/min/index.md)
      11) [percentile](/api/python/v2.2/semantics/std/aggregates/percentile/index.md)
      12) [product](/api/python/v2.2/semantics/std/aggregates/product/index.md)
      13) [rank](/api/python/v2.2/semantics/std/aggregates/rank/index.md)
      14) [rank\_asc](/api/python/v2.2/semantics/std/aggregates/rank_asc/index.md)
      15) [rank\_desc](/api/python/v2.2/semantics/std/aggregates/rank_desc/index.md)
      16) [stddev\_samp](/api/python/v2.2/semantics/std/aggregates/stddev_samp/index.md)
      17) [string\_join](/api/python/v2.2/semantics/std/aggregates/string_join/index.md)
      18) [sum](/api/python/v2.2/semantics/std/aggregates/sum/index.md)
      19) [top](/api/python/v2.2/semantics/std/aggregates/top/index.md)
      20) [variance](/api/python/v2.2/semantics/std/aggregates/variance/index.md)
      21) [variance\_samp](/api/python/v2.2/semantics/std/aggregates/variance_samp/index.md)

## Referenced By

1. [RelationalAI Documentation](/index.md)1) [Build With RelationalAI](/build/index.md)1. [Use advanced reasoning](/build/reasoning/index.md)1) [Path reasoning](/build/reasoning/path/index.md)1. [Use path results](/build/reasoning/path/use-path-results/index.md)1) [Count paths without enumerating them](/build/reasoning/path/use-path-results/index.md#count-paths-without-enumerating-them)
         2) [Prescriptive reasoning](/build/reasoning/prescriptive/index.md) / [Solve a decision problem](/build/reasoning/prescriptive/decision-problems/index.md)1) [Add constraints](/build/reasoning/prescriptive/decision-problems/constraints/index.md)1. [Use common constraint patterns](/build/reasoning/prescriptive/decision-problems/constraints/index.md#use-common-constraint-patterns)
         3) [Rules-based reasoning](/build/reasoning/rules-based/index.md)1) [Aggregate and group data](/build/reasoning/rules-based/aggregate-and-group-data/index.md)1. [Group results with `per()`](/build/reasoning/rules-based/aggregate-and-group-data/index.md#group-results-with-per)
               2. [Scope aggregate inputs with aggregate-local `.where()`](/build/reasoning/rules-based/aggregate-and-group-data/index.md#scope-aggregate-inputs-with-aggregate-local-where)
