Skip to content

type_bridge.expressions.aggregate

aggregate

Aggregate expressions for database-side calculations.

AggregateExpr 

AggregateExpr(attr_type=None, function='count', field_name=None)

Bases: Expression

Type-safe aggregate expression for database-side calculations.

Represents aggregations like sum(age), avg(score), count(*), etc.

Create an aggregate expression.

Parameters:

Name Type Description Default
attr_type type[T] | None

Attribute type to aggregate (None for count)

 None
function Literal['sum', 'mean', 'max', 'min', 'count', 'median', 'std']

Aggregation function (use 'mean' for TypeDB 3.x, not 'avg')

 'count'
field_name str | None

Python field name (used for result keys, e.g., 'salary' → 'avg_salary')

 None
Note

The user-facing avg() method automatically converts to 'mean'. TypeDB 3.x uses 'mean' instead of 'avg'.

Source code in type_bridge/expressions/aggregate.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
def __init__(
    self,
    attr_type: type[T] | None = None,
    function: Literal["sum", "mean", "max", "min", "count", "median", "std"] = "count",
    field_name: str | None = None,
):
    """Create an aggregate expression.

    Args:
        attr_type: Attribute type to aggregate (None for count)
        function: Aggregation function (use 'mean' for TypeDB 3.x, not 'avg')
        field_name: Python field name (used for result keys, e.g., 'salary' → 'avg_salary')

    Note:
        The user-facing avg() method automatically converts to 'mean'.
        TypeDB 3.x uses 'mean' instead of 'avg'.
    """
    self.attr_type = attr_type
    self.function = function
    self.field_name = field_name

    # Validate attr_type requirement
    if function != "count" and attr_type is None:
        raise ValueError(f"{function.upper()} requires an attribute type")

to_value_ast 

to_value_ast(var=None)

Convert to AST FunctionCallValue.

Parameters:

Name Type Description Default
var str | None

Variable name required for aggregate expressions (e.g., "$e")

 None

Raises:

Type Description
ValueError

If var is not provided (aggregates require context)
Source code in type_bridge/expressions/aggregate.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
def to_value_ast(self, var: str | None = None) -> "Value":
    """Convert to AST FunctionCallValue.

    Args:
        var: Variable name required for aggregate expressions (e.g., "$e")

    Raises:
        ValueError: If var is not provided (aggregates require context)
    """
    from type_bridge.query.ast import FunctionCallValue

    if var is None:
        raise ValueError("AggregateExpr.to_value_ast() requires a variable name")

    if self.function == "count":
        return FunctionCallValue(function="count", args=[var])

    assert self.attr_type is not None
    from type_bridge.expressions.utils import generate_attr_var

    attr_var = generate_attr_var(var, self.attr_type)
    return FunctionCallValue(function=self.function, args=[attr_var])

to_typeql 

to_typeql(var)

Deprecated: Generate TypeQL pattern for this aggregation.

Source code in type_bridge/expressions/aggregate.py 
71
72
73
74
75
76
77
78
79
80
def to_typeql(self, var: str) -> str:
    """Deprecated: Generate TypeQL pattern for this aggregation."""
    if self.function == "count":
        return f"count({var})"

    assert self.attr_type is not None
    from type_bridge.expressions.utils import generate_attr_var

    attr_var = generate_attr_var(var, self.attr_type)
    return f"{self.function}({attr_var})"

get_fetch_key 

get_fetch_key()

Get the key to use in fetch results.

Note

AUTOMATIC CONVERSION: TypeQL 'mean' → result key 'avg' For user-facing consistency, result keys use 'avg' even though TypeDB internally uses 'mean'. This matches the method name.

Returns:

Type Description
str

String key for accessing aggregate result
Example

Person.salary.avg() generates TypeQL 'mean($personsalary)' but result key is 'avg_salary' (using field name, not attribute type name)

Source code in type_bridge/expressions/aggregate.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def get_fetch_key(self) -> str:
    """Get the key to use in fetch results.

    Note:
        AUTOMATIC CONVERSION: TypeQL 'mean' → result key 'avg'
        For user-facing consistency, result keys use 'avg' even though
        TypeDB internally uses 'mean'. This matches the method name.

    Returns:
        String key for accessing aggregate result

    Example:
        Person.salary.avg() generates TypeQL 'mean($personsalary)'
        but result key is 'avg_salary' (using field name, not attribute type name)
    """
    if self.function == "count":
        return "count"

    assert self.attr_type is not None
    # AUTOMATIC CONVERSION: Map 'mean' back to 'avg' for user-facing API
    func_name = "avg" if self.function == "mean" else self.function

    # Use field_name if available (from FieldRef), otherwise fall back to attribute type name
    if self.field_name:
        return f"{func_name}_{self.field_name}"
    else:
        attr_type_name = self.attr_type.get_attribute_name()
        return f"{func_name}_{attr_type_name.lower()}"