fn_registry/python/functions/datascience/groupby_stats_duckdb.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
groupby_stats_duckdb	function	py	datascience	1.0.0	impure	def groupby_stats_duckdb(db_path: str, table: str, group_by: str, measures: list, aggs: list = None, top_n: int = 15) -> dict	Agregaciones GROUP BY con push-down SQL en DuckDB: para cada measure numerica calcula mean/median/std/min/max por grupo (split-apply-combine en el motor), trayendo solo una fila por grupo. Nucleo de un capitulo de agregacion/OLAP de un EDA. count = tamanio del grupo, independiente de measures.	eda groupby aggregation olap duckdb datascience push-down split-apply-combine	duckdb_query_readonly_py_infra			false	error_go_core		name desc db_path Ruta al archivo DuckDB. Debe existir; el modo read_only NO crea la base. Path inexistente -> {status:'error'} sin lanzar. name desc table Nombre de la tabla. Se interpola citado con dobles comillas (soporta nombres con espacios; las comillas internas se escapan). name desc group_by Columna por la que agrupar. Se interpola citada. Sus valores distintos son las claves de los grupos. name desc measures Lista de columnas numericas a agregar. Lista vacia es valida: cada grupo trae solo su tamanio `n` y `stats` vacio. name desc aggs Lista de agregaciones. None (default) = ['count','mean','median','std','min','max']. Validas: count (tamanio del grupo, va a `n`), mean->avg, median, std->stddev_samp, min, max (estas cinco por measure). Agg desconocido -> error. name desc top_n Maximo de grupos a devolver, ordenados por tamanio de grupo descendente (default 15). Internamente se piden top_n+1 para detectar truncado.	dict. En exito {status:'ok', group_by, measures:[...], aggs:[...], n_groups:int, truncated:bool, groups:[{key:<valor grupo>, n:int, stats:{<measure>:{mean,median,std,min,max}}}], note:str}. Las estadisticas son float o None (p.ej. std de un grupo de 1 fila -> NULL -> None). En error {status:'error', error:str} (no lanza).	true	agrega por grupo con valores conocidos db inexistente devuelve error sin lanzar measures vacias agrega solo count columna con espacio agrupa bien	python/functions/datascience/groupby_stats_duckdb_test.py	python/functions/datascience/groupby_stats_duckdb.py

Ejemplo

import duckdb
from datascience import groupby_stats_duckdb

# Cargar el titanic en una tabla DuckDB de prueba.
db = "/tmp/titanic.duckdb"
con = duckdb.connect(db)
con.execute(
    "CREATE TABLE titanic AS "
    "SELECT * FROM read_csv_auto('https://raw.githubusercontent.com/"
    "datasciencedojo/datasets/master/titanic.csv')"
)
con.close()

# Agrupar por sexo midiendo edad y tarifa.
res = groupby_stats_duckdb(db, "titanic", "Sex", ["Age", "Fare"])
print(res["status"])          # ok
print(res["n_groups"])        # 2  (male, female)
for g in res["groups"]:
    print(g["key"], g["n"], round(g["stats"]["Fare"]["mean"], 2))
# female 314 44.48
# male   577 25.52

Cuando usarla

Cuando en un EDA necesitas el clasico split-apply-combine: "para cada categoria de X, ¿cuanto vale en media/mediana/desviacion/min/max la metrica Y?". Es el nucleo de un capitulo de agregacion/OLAP. Usala antes de pintar barras o boxplots por grupo, para detectar segmentos con comportamiento distinto, o para resumir una tabla grande sin traer las filas a RAM: todo el GROUP BY ocurre push-down en el motor de DuckDB y solo viaja una fila por grupo. top_n te deja quedarte con los grupos mas poblados.

Gotchas

• Funcion impura: lee un archivo DuckDB del disco (read_only, nunca lo modifica). La tabla debe existir ya en el .db (no carga CSV; para eso crea la tabla antes).
• Identificadores (tabla, group_by, measures) se interpolan citados con dobles comillas y escapando las internas: soporta nombres con espacios y evita inyeccion. No pases expresiones SQL como group_by/measure — solo nombres de columna.
• count es el tamanio del grupo (COUNT(*)), independiente de las measures: se refleja en el campo n de cada grupo, NO como clave dentro de stats. Las claves de stats[measure] son las measure-aggs efectivas (mean/median/std/min/max menos count).
• std usa stddev_samp (muestral, n-1): un grupo con una sola fila da NULL -> None. Las measures pueden contener NULLs; cada agregada los ignora segun la semantica de DuckDB.
• truncated:True indica que habia mas grupos que top_n (se devolvieron los top_n mayores por tamanio). Sube top_n si necesitas todos los grupos.
• Si measures esta vacio, cada grupo trae solo n y stats == {} (valido, util para un simple conteo por categoria).