Funciones de agregación de DataStore - ClickHouse Documentation

DataStore ofrece un soporte completo para funciones de agregación y de ventana, aprovechando las potentes capacidades de agregación SQL de ClickHouse.

Agregaciones básicas

Métodos integrados

Método	Equivalente en SQL	Descripción
`sum()`	`SUM()`	Suma de valores
`mean()`	`AVG()`	Promedio/media
`count()`	`COUNT()`	Cuenta los valores no nulos
`min()`	`MIN()`	Valor mínimo
`max()`	`MAX()`	Valor máximo
`median()`	`MEDIAN()`	Mediana
`std()`	`stddevPop()`	Desviación estándar
`var()`	`varPop()`	Varianza
`nunique()`	`COUNT(DISTINCT)`	Cuenta los valores únicos

Ejemplos:

from pathlib import Path
Path("sales.csv").write_text("""\
region,product,category,amount,quantity,price,date,order_id
East,Widget,Electronics,5200,10,120,2024-01-15,1001
West,Gadget,Electronics,800,5,160,2024-02-20,1002
East,Gizmo,Home,6500,3,100,2024-03-10,1003
North,Widget,Electronics,4500,6,150,2024-06-18,1004
West,Gadget,Electronics,2000,8,250,2024-09-14,1005
""")

from chdb import datastore as pd

ds = pd.read_csv("sales.csv")

# Agregación de una columna
total = ds['amount'].sum()
average = ds['amount'].mean()
count = ds['amount'].count()

# Todas las agregaciones
print(ds['amount'].sum())    # Total
print(ds['amount'].mean())   # Media
print(ds['amount'].std())    # Desviación estándar
print(ds['amount'].median()) # Mediana
print(ds['amount'].nunique()) # Recuento de valores únicos

Agregaciones de GroupBy

Agregación simple

# Agrupar y agregar
result = ds.groupby('category')['amount'].sum()
result = ds.groupby('region')['sales'].mean()

Agregaciones múltiples

# Sintaxis de diccionario
result = ds.groupby('category').agg({
    'amount': 'sum',
    'quantity': 'mean',
    'order_id': 'count'
})

# Lista de agregaciones por columna
result = ds.groupby('category').agg({
    'amount': ['sum', 'mean', 'max'],
    'quantity': ['sum', 'count']
})

Agregaciones con nombre

# Agregación con nombre (estilo pandas)
result = ds.groupby('region').agg(
    total_amount=('amount', 'sum'),
    avg_quantity=('quantity', 'mean'),
    order_count=('order_id', 'count'),
    max_price=('price', 'max')
)

Múltiples claves de agrupación

# Agrupar por múltiples columnas
result = ds.groupby(['region', 'category']).agg({
    'amount': 'sum',
    'quantity': 'sum'
})

Agregaciones estadísticas

Método	Equivalente en SQL	Descripción
`quantile(q)`	`quantile(q)`	cuantil q-ésimo (0-1)
`skew()`	`skewPop()`	Asimetría
`kurt()`	`kurtPop()`	Curtosis
`corr()`	`corr()`	Correlación
`cov()`	`covar()`	Covarianza
`sem()`	-	Error estándar de la media

Ejemplos:

# Cuantiles
q50 = ds['amount'].quantile(0.5)  # Mediana
q95 = ds['amount'].quantile(0.95) # Percentil 95

# Múltiples cuantiles
quantiles = ds['amount'].quantile([0.25, 0.5, 0.75])

# Correlación entre columnas
correlation = ds[['sales', 'marketing_spend']].corr()

Agregaciones condicionales

Funciones de agregación condicional específicas de ClickHouse.

Función	ClickHouse	Descripción
`sum_if(cond)`	`sumIf()`	Suma si se cumple la condición
`count_if(cond)`	`countIf()`	Recuento si se cumple la condición
`avg_if(cond)`	`avgIf()`	Promedio si se cumple la condición
`min_if(cond)`	`minIf()`	Mínimo si se cumple la condición
`max_if(cond)`	`maxIf()`	Máximo si se cumple la condición

Ejemplos:

from chdb.datastore import F, Field

# Sumar solo los pedidos de alto valor
high_value_sum = F.sum_if(Field('amount'), Field('amount') > 1000)

# Contar los usuarios activos
active_count = F.count_if(Field('status') == 'active')

# En el contexto de groupby
result = ds.groupby('region').agg({
    'total': ('amount', 'sum'),
    'high_value': ('amount', F.sum_if(Field('amount') > 1000)),
})

Agregaciones de recopilación

Funciones específicas de ClickHouse que recopilan valores.

FUNCTION	ClickHouse	Description
`group_array()`	`groupArray()`	Recopila en un array
`group_uniq_array()`	`groupUniqArray()`	Recopila valores únicos en un array
`group_concat(sep)`	`groupConcat()`	Concatena cadenas
`top_k(n)`	`topK(n)`	Top K de valores más frecuentes
`any()`	`any()`	Un valor cualquiera
`any_last()`	`anyLast()`	Último valor
`first_value()`	`first_value()`	Primer valor en orden
`last_value()`	`last_value()`	Último valor en orden

Ejemplos:

from chdb.datastore import F, Field

# Recopila todas las etiquetas por categoría
result = ds.groupby('category').agg({
    'all_tags': ('tag', F.group_array()),
    'unique_tags': ('tag', F.group_uniq_array())
})

# Obtén los 5 productos principales por región
result = ds.groupby('region').agg({
    'top_products': ('product_id', F.top_k(5))
})

Funciones de ventana

Funciones de clasificación

Función	SQL	Descripción
`row_number()`	`ROW_NUMBER()`	Número de fila secuencial
`rank()`	`RANK()`	Rango con huecos
`dense_rank()`	`DENSE_RANK()`	Rango sin huecos
`ntile(n)`	`NTILE(n)`	Divide en n grupos
`percent_rank()`	`PERCENT_RANK()`	Rango porcentual (0-1)
`cume_dist()`	`CUME_DIST()`	Distribución acumulada

Ejemplos:

from chdb.datastore import F, Field

# Agregar número de fila
ds['row_num'] = F.row_number().over(order_by='date')

# Rango dentro de grupos
ds['rank'] = F.rank().over(
    partition_by='category',
    order_by='sales'
)

# Rango denso (sin huecos)
ds['dense_rank'] = F.dense_rank().over(
    partition_by='region',
    order_by=('revenue', 'desc')
)

# Dividir en cuartiles
ds['quartile'] = F.ntile(4).over(order_by='score')

Funciones de valor

Función	SQL	Descripción
`lag(n)`	`LAG(col, n)`	Valor de la fila anterior
`lead(n)`	`LEAD(col, n)`	Valor de la fila siguiente
`first_value()`	`FIRST_VALUE()`	Primer valor de la ventana
`last_value()`	`LAST_VALUE()`	Último valor de la ventana
`nth_value(n)`	`NTH_VALUE(col, n)`	Enésimo valor de la ventana

Ejemplos:

# Valor anterior y siguiente
ds['prev_price'] = F.lag('price', 1).over(order_by='date')
ds['next_price'] = F.lead('price', 1).over(order_by='date')

# Primero y último en la partición
ds['first_order'] = F.first_value('amount').over(
    partition_by='customer_id',
    order_by='date'
)

Funciones acumulativas

Método	Descripción
`cumsum()`	Suma acumulada
`cummax()`	Máximo acumulado
`cummin()`	Mínimo acumulado
`cumprod()`	Producto acumulado
`diff(n)`	Diferencia respecto a n filas atrás
`pct_change(n)`	Cambio porcentual respecto a n filas atrás

Ejemplos:

# Cálculos acumulados
ds['running_total'] = ds['amount'].cumsum()
ds['running_max'] = ds['amount'].cummax()

# Con agrupación
ds['group_cumsum'] = ds.groupby('category')['amount'].cumsum()

# Período a período
ds['daily_diff'] = ds['sales'].diff(1)
ds['pct_change'] = ds['sales'].pct_change(1)

Ventanas móviles

# Agregaciones de ventana deslizante
ds['rolling_avg'] = ds['price'].rolling(window=7).mean()
ds['rolling_sum'] = ds['amount'].rolling(window=30).sum()
ds['rolling_std'] = ds['value'].rolling(window=10).std()

# Ventanas en expansión
ds['expanding_max'] = ds['price'].expanding().max()
ds['expanding_sum'] = ds['amount'].expanding().sum()

Espacio de nombres F

El espacio de nombres F proporciona acceso a las funciones de ClickHouse.

Importación

from chdb.datastore import F, Field

Uso de funciones F

# Agregaciones
F.sum(Field('amount'))
F.avg(Field('price'))
F.count(Field('id'))

# Estadísticas
F.quantile(Field('value'), 0.95)
F.stddev_pop(Field('score'))
F.corr(Field('x'), Field('y'))

# Condicionales
F.sum_if(Field('amount'), Field('status') == 'completed')
F.count_if(Field('is_active'))

# Cadenas de texto
F.length(Field('name'))
F.upper(Field('text'))

# Fecha/Hora
F.to_year(Field('date'))
F.date_diff('day', Field('start'), Field('end'))

# Arrays
F.array_sum(Field('values'))
F.array_avg(Field('scores'))

# Matemáticas
F.abs(Field('delta'))
F.round(Field('price'), 2)
F.floor(Field('value'))
F.ceil(Field('value'))

F con funciones de ventana

# Definir el marco de ventana
window = F.window(
    partition_by='category',
    order_by='date',
    rows_between=(-7, 0)  # Fila actual y las 7 anteriores
)

ds['rolling_avg'] = F.avg(Field('price')).over(window)

Patrones de agregación comunes

Top N por grupo

# Top 3 productos por categoría según ventas
result = (ds
    .assign(rank=F.row_number().over(
        partition_by='category',
        order_by=('sales', 'desc')
    ))
    .filter(ds['rank'] <= 3)
)

Suma acumulada

# Total acumulado de ventas
ds['running_total'] = F.sum('amount').over(
    order_by='date',
    rows_between=(None, 0)  # Todas las filas hasta la actual
)

Media móvil

# promedio móvil de 7 días
ds['ma_7'] = F.avg('price').over(
    order_by='date',
    rows_between=(-6, 0)
)

Comparación interanual

# Comparación interanual
ds['prev_year_sales'] = F.lag('sales', 12).over(
    partition_by='product_id',
    order_by='month'
)
ds['yoy_growth'] = (ds['sales'] - ds['prev_year_sales']) / ds['prev_year_sales']

Clasificación percentil

# Clasificar clientes por gasto total
ds['spend_percentile'] = F.percent_rank().over(order_by='total_spend')

Resumen de métodos de agregación

Categoría	Métodos
Básico	`sum`, `mean`, `count`, `min`, `max`, `median`
Estadístico	`std`, `var`, `quantile`, `skew`, `kurt`, `corr`, `cov`
Condicional	`sum_if`, `count_if`, `avg_if`, `min_if`, `max_if`
Colección	`group_array`, `group_uniq_array`, `group_concat`, `top_k`
clasificación	`row_number`, `rank`, `dense_rank`, `ntile`, `percent_rank`
Valor	`lag`, `lead`, `first_value`, `last_value`, `nth_value`
Acumulativo	`cumsum`, `cummax`, `cummin`, `cumprod`, `diff`, `pct_change`
móvil	`rolling().mean/sum/std/...`, `expanding().mean/sum/...`

​Agregaciones básicas

​Métodos integrados

​Agregaciones de GroupBy

​Agregación simple

​Agregaciones múltiples

​Agregaciones con nombre

​Múltiples claves de agrupación

​Agregaciones estadísticas

​Agregaciones condicionales

​Agregaciones de recopilación

​Funciones de ventana

​Funciones de clasificación

​Funciones de valor

​Funciones acumulativas

​Ventanas móviles

​Espacio de nombres F

​Importación

​Uso de funciones F

​F con funciones de ventana

​Patrones de agregación comunes

​Top N por grupo

​Suma acumulada

​Media móvil

​Comparación interanual

​Clasificación percentil

​Resumen de métodos de agregación

Agregaciones básicas

Métodos integrados

Agregaciones de GroupBy

Agregación simple

Agregaciones múltiples

Agregaciones con nombre

Múltiples claves de agrupación

Agregaciones estadísticas

Agregaciones condicionales

Agregaciones de recopilación

Funciones de ventana

Funciones de clasificación

Funciones de valor

Funciones acumulativas

Ventanas móviles

Espacio de nombres F

Importación

Uso de funciones F

F con funciones de ventana

Patrones de agregación comunes

Top N por grupo

Suma acumulada

Media móvil

Comparación interanual

Clasificación percentil

Resumen de métodos de agregación