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'])
agg — varias operaciones, GROUP BY y ranking¶
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 | ✓ |
countlo admite todo: cuenta los valores no nulos y no mira cuáles son. Ojo con undict: elNonede Python se guarda como el JSONnull, que no es un NULL de SQL y cuenta.maxde un booleano no existe en PostgreSQL; para «¿hay alguno aTrue?» estácountcon 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
maxsería el último por orden alfabético, no el último declarado. Para repartir por estado:countcongroup_by. - Una expresión de
AggFieldes 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
strequivale aGroupByField(field=..., trunc=None). - Las columnas DATETIME / TIMESTAMP exigen
truncexplícito: agrupar por un instante no agrupa nada. - Las columnas FLOAT / DOUBLE / DECIMAL / NUMERIC / REAL no se pueden agrupar.
truncsolo 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.