Saltar a contenido

Agregaciones

Cuatro atajos y un método general. Todos aceptan los mismos filtros que find_many, y devuelven un AggregationResult.

Los atajos

dao.sum(agg_fields=['importe'], activo=True)
dao.mean(agg_fields=['importe'])
dao.max(agg_fields=['importe', 'unidades'])
dao.min(agg_fields=['importe'])
res = dao.sum(agg_fields=['importe'])
res.rows[0].data          # {'sum_importe': 1234.5}

agg — varias operaciones, GROUP BY y ranking

from database.public import AggRequest, AggField, GroupByField, DatetimeTrunc, AggOrderBy
res = dao.agg(AggRequest(
    aggregations={'sum': ['importe'], 'count': ['id']},
))
res.rows[0].group     # {}
res.rows[0].data      # {'sum_importe': 1234.5, 'count_id': 42}
res = dao.agg(AggRequest(
    aggregations={'sum': ['importe'], 'count': ['id']},
    group_by=['estado', GroupByField(field='creado_en', trunc=DatetimeTrunc.month)],
))

for row in res.rows:
    print(row.group, row.data)
    # {'estado': 'publicado', 'creado_en_month': '2026-09-01'} {'sum_importe': 900.0, ...}
res = dao.agg(AggRequest(
    aggregations={'sum': [AggField(expr='ingresos-costes', alias='margen')]},
    group_by=['estado'],
))
res = dao.agg(AggRequest(
    aggregations={'count': ['id']},
    group_by=['referencia_producto'],
    order_by=[AggOrderBy(operation='count', field='id', direction='desc')],
    limit=10,
))

Las piezas

Clase Para qué
AggRequest Qué calcular: aggregations, group_by, order_by, limit
AggField Una expresión aritmética entre columnas, con alias opcional
GroupByField Un campo de agrupación, con trunc para fechas
DatetimeTrunc La granularidad del truncado temporal
AggOrderBy Ordenar por una columna calculada: operation + field + direction

Operaciones soportadas: sum, mean, max, min, count.

Qué admite cada tipo

Tipo de la columna count sum · mean max · min
int, bigint, smallint, float, numeric ✓ ✓ ✓ (un número)
datetime, timestamptz, date, time ✓ ✓ (en ISO 8601)
str, text ✓ ✓ (el texto, por la collation de la columna)
bool, bytes, dict (JSON), vector ✓
Cifrada, hasheada o enumerado ✓
  • count lo admite todo: cuenta los valores no nulos y no mira cuáles son. Ojo con un dict: el None de Python se guarda como el JSON null, que no es un NULL de SQL y cuenta.
  • max de un booleano no existe en PostgreSQL; para «¿hay alguno a True?» está count con el filtro.
  • Una columna cifrada se ordenaría por su texto cifrado —sin relación con el valor— y devolvería el cifrado; una hasheada devolvería el hash, que el cliente no expone en ninguna lectura. Las dos solo se cuentan.
  • Un enumerado se guarda como texto en todos los motores, así que su max sería el último por orden alfabético, no el último declarado. Para repartir por estado: count con group_by.
  • Una expresión de AggField es aritmética: todas sus columnas tienen que ser numéricas.

Está escrito en cada DAO generado (_AGG_COLUMNS), y sale del tipo del schema.

Una agregación imposible es un error

Lo que no se puede hacer tal y como se pidió —un campo que no existe, un tipo que no admite la operación, una expresión sobre un texto, un group_by o un order_by imposibles, un trunc sobre algo que no es un DATETIME/TIMESTAMP— hace fallar la petición entera: no se consulta nada, success es False, rows está vacío y errors dice por qué.

res = dao.agg(AggRequest(aggregations={'count': ['id'], 'sum': ['titulo']}))
res.success   # False
res.errors    # ["Campo 'titulo' de tipo 'str' no es válido para 'sum': admite count, max, min"]

No lanza una excepción: es el mismo AggregationResult, y tai-api lo convierte en un 422 con el motivo. Antes, lo imposible se descartaba con un aviso en warnings y, si había algo válido al lado, success era True y la clave simplemente faltaba en data.

DatetimeTrunc admite year, quarter, month, week, day, hour, minute (vía DATE_TRUNC) y los intervalos 12h, 6h, 3h, 30min, 15min (vía DATE_BIN). La clave resultante en AggRow.group es <campo>_<trunc>, por ejemplo creado_en_month.

Reglas del group_by

  • Un str equivale a GroupByField(field=..., trunc=None).
  • Las columnas DATETIME / TIMESTAMP exigen trunc explícito: agrupar por un instante no agrupa nada.
  • Las columnas FLOAT / DOUBLE / DECIMAL / NUMERIC / REAL no se pueden agrupar.
  • trunc solo vale en DATETIME / TIMESTAMP. En cualquier otra columna —también en un DATE— es un error: ignorarlo agruparía por otra cosa de la que se pidió.

El resultado

res.success            # bool: todo lo pedido se ha hecho, o nada
res.rows               # List[AggRow] — cada una con .group y .data
res.group_by           # los campos de agrupación aplicados
res.processed_fields   # los campos calculados
res.warnings           # lo que no cambia el resultado (una operación pedida sin campos)
res.errors             # por qué no se ha podido; con alguno, success es False
res.metadata

Sin group_by, rows tiene una sola fila con group = {}. Con él, una por combinación.

Las claves de data son <operacion>_<campo> (sum_importe, count_id), o el alias si lo declaraste.

Con filtros y RLS

res = dao.agg(
    AggRequest(aggregations={'sum': ['importe']}),
    min_creado_en=datetime(2026, 1, 1),
    estado='publicado',
    rls=RLS(target_model=Empresa, target_column='id', values=[1, 2]),
)

verbose=True emite un log detallado de cada campo, expresión y fila procesada — útil cuando una agregación devuelve menos de lo que esperabas.