avg()#

relationalai.std.aggregates
#avg(*args: Producer, per: list[Producer] = []) -> Expression

Calculates the average of all distinct values produced one or more Producer objects. When multiple producers are provided, the aggregation is done over rows (v1, v2, ... vn) representing the distinct combinations of values produced by the arguments, with the average taken over the last column. Pass a list of Producer objects to the optional per parameter to group values and compute the average per group. Must be called in a rule or query context.

Parameters#

NameTypeDescription
*argsProducerOne or more Producer objects.
perList[Producer]An optional list of Producer objects used to group arguments. (Default: [])

Returns#

An Expression object.

Example#

Use avg() to compute the average of distinct values produced by a Producer object:

#import relationalai as rai
from relationalai.std import aggregates, alias


# =====
# SETUP
# =====

model = rai.Model("MyModel")
Person = model.Type("Person")

with model.rule():
    Person.add(id=1).set(name="Joe", age=41)
    Person.add(id=2).set(name="Jane", age=39)
    Person.add(id=3).set(name="John", age=39)


# =======
# EXAMPLE
# =======

with model.query() as select:
    person = Person()
    # Compute the average of the person.age property. Note that properties use set
    # semantics, so the average is computed over distinct age values and not over
    # the ages of each person.
    avg = aggregates.avg(person.age)
    response = select(alias(avg, "avg_age_distinct"))

print(response.results)
#   avg_age_distinct
# 0             40.0

When you pass multiple Producer objects to avg(), the aggregation is performed over the expansion of the arguments into distinct rows of the form (v1, v2, ..., vn) where 1, v2, …, vn are the values produced by the Producer objects. The average is taken over the values in the last column of each row.

You can use this, for example, to compute the average age of all people in the preceding example:

## Get the average age of all people.
with model.query() as select:
    person = Person()
    avg_age = aggregates.avg(person, person.age)
    response = select(alias(avg_age, "avg_age"))

print(response.results)
#      avg_age
# 0  39.666667

To group values and compute the average for each group, pass a list of one or more Producer objects to the optional per keyword argument. In the following example, the person object is passed to per to compute the average age of a person’s friends:

## Set a multi-valued friend property for each person.
with model.rule():
    joe = Person(name="Joe")
    jane = Person(name="Jane")
    john = Person(name="John")
    joe.friends.extend([jane, john])
    jane.friends.extend([joe])
    john.friends.extend([joe])

with model.query() as select:
    person = Person()
    # Compute the average age of a person's friends.
    avg_friend_age = aggregates.avg(person.friends, person.friends.age, per=[person])
    response = select(person.name, alias(avg_friend_age, "avg_friend_age"))

print(response.results)
#    name  avg_friend_age
# 0  Jane            41.0
# 1   Joe            39.0
# 2  John            41.0

See Also#