Per

relationalai.semantics.std.aggregates

Group aggregation context for computing per-group aggregates.

Use this class to perform aggregations within groups defined by specific values.

Methods

.sum()

Per.sum(*args: AggValue) -> Aggregate

Compute sum per group.

Parameters:

• *args

  (AggValue, default: ()) - Values to sum within each group.

Returns:

• Aggregate - An Aggregate expression for per-group sum. Returns Number if the input is Number, or Float if the input is Float.

Examples:

Sum order amounts per customer:

>>> select(Customer, aggregates.sum(Order.amount).per(Customer).where(Order.customer == Customer))

.count()

Per.count(*args: AggValue) -> Aggregate

Count values per group.

Parameters:

• *args

  (AggValue, default: ()) - Values to count within each group.

Returns:

• Aggregate - An Aggregate expression for per-group count. Returns Integer.

Examples:

Count employees per department:

>>> select(Department, aggregates.count(Employee).per(Department).where(Employee.department == Department))

.min()

Per.min(*args: AggValue) -> Aggregate

Find minimum per group.

Parameters:

• *args

  (AggValue, default: ()) - Values to find minimum from within each group.

Returns:

• Aggregate - An Aggregate expression for per-group minimum. Returns the same type as the input.

Examples:

Find minimum salary per department:

>>> select(Department, aggregates.min(Employee.salary).per(Department).where(Employee.department == Department))

.max()

Per.max(*args: AggValue) -> Aggregate

Find maximum per group.

Parameters:

• *args

  (AggValue, default: ()) - Values to find maximum from within each group.

Returns:

• Aggregate - An Aggregate expression for per-group maximum. Returns the same type as the input.

Examples:

Find maximum order amount per customer:

>>> select(Customer, aggregates.max(Order.amount).per(Customer).where(Order.customer == Customer))

.avg()

Per.avg(*args: AggValue) -> Aggregate

Compute average per group.

Parameters:

• *args

  (AggValue, default: ()) - Values to average within each group.

Returns:

• Aggregate - An Aggregate expression for per-group average. Returns ScaledNumber if the input is Number, or Float if the input is Float.

Examples:

Compute average salary per department:

>>> select(Department, aggregates.avg(Employee.salary).per(Department).where(Employee.department == Department))

.string_join()

Per.string_join(*args: AggValue, sep="", index=1) -> Aggregate

Join strings per group.

Parameters:

• *args

  (AggValue, default: ()) - String values to join within each group.

• sep

  (, default: "") - Separator string. Default: empty string.

• index

  (, default: 1) - Index parameter. Default: 1.

Returns:

• Aggregate - An Aggregate expression for per-group string join. Returns String.

Examples:

Join employee names per department:

>>> select(Department, aggregates.string_join(Employee.name, sep=", ").per(Department).where(Employee.department == Department))

.rank()

Per.rank(*args: AggValue | Ordering) -> Aggregate

Compute rank per group.

Parameters:

• *args

  (AggValue | Ordering, default: ()) - Values or Ordering specs to rank by within each group.

Returns:

• Aggregate - An Aggregate expression for per-group rank. Returns Integer.

Examples:

Rank employees by salary within each department:

>>> select(Employee, aggregates.rank(aggregates.desc(Employee.salary)).per(Department).where(Employee.department == Department))

.limit()

Per.limit(limit_: int, *args: AggValue | Ordering) -> Aggregate

Limit results per group.

Parameters:

• limit_

  (int) - Maximum results per group.

• *args

  (AggValue | Ordering, default: ()) - Values or Ordering specs to order by.

Returns:

• Aggregate - An Aggregate expression for per-group limited results.

Examples:

Get top 3 employees per department by salary:

>>> select(Employee).where(aggregates.limit(3, aggregates.desc(Employee.salary)).per(Department).where(Employee.department == Department))

.rank_asc()

Per.rank_asc(*args: AggValue) -> Aggregate

Compute ascending rank per group.

Parameters:

• *args

  (AggValue, default: ()) - Values to rank in ascending order within each group.

Returns:

• Aggregate - An Aggregate expression for per-group ascending rank. Returns Integer.

Examples:

Rank products by price within each category (lowest first):

>>> select(Product, aggregates.rank_asc(Product.price).per(Category))

.rank_desc()

Per.rank_desc(*args: AggValue) -> Aggregate

Compute descending rank per group.

Parameters:

• *args

  (AggValue, default: ()) - Values to rank in descending order within each group.

Returns:

• Aggregate - An Aggregate expression for per-group descending rank. Returns Integer.

Examples:

Rank products by sales within each category (highest first):

>>> select(Product, aggregates.rank_desc(Product.sales).per(Category).where(Product.category == Category))

.top()

Per.top(limit: int, *args: AggValue) -> Aggregate

Get top N per group.

Parameters:

• limit

  (int) - Number of top results per group.

• *args

  (AggValue, default: ()) - Values to order by (descending).

Returns:

• Aggregate - An Aggregate expression for per-group top N.

Examples:

Get top 5 products by revenue per store:

>>> select(Product).where(aggregates.top(5, Product.revenue).per(Store).where(Product.store == Store))

.bottom()

Per.bottom(limit: int, *args: AggValue) -> Aggregate

Get bottom N per group.

Parameters:

• limit

  (int) - Number of bottom results per group.

• *args

  (AggValue, default: ()) - Values to order by (ascending).

Returns:

• Aggregate - An Aggregate expression for per-group bottom N.

Examples:

Get bottom 3 products by sales per category:

>>> select(Product).where(aggregates.bottom(3, Product.sales).per(Category).where(Product.category == Category))

Inheritance Hierarchy

Returned By

 semantics > std > aggregates
└──  per