Aggregation - Tablestore SDK for Python - Tablestore - Centro de documentación de Alibaba Cloud

Utilice Tablestore SDK for Python para realizar agregaciones métricas y agrupamientos en los resultados de un índice de búsqueda.

Requisitos previos

Instale Tablestore SDK for Python e inicialice un cliente.

La función de agregación requiere la versión 5.2.1 del SDK o posterior. Se recomienda utilizar la versión más reciente del SDK.

Descripción

La agregación calcula métricas o crea grupos a partir de los resultados de consulta de un índice de búsqueda. Agregue objetos de agregación métrica a SearchQuery.aggs y objetos de agrupamiento a SearchQuery.group_bys. Cada name en una solicitud debe ser único e identifica el resultado correspondiente en la respuesta. Para obtener únicamente los resultados de la agregación, establezca limit en 0.

Función	Descripción
Min, Max, Sum, Avg	Calculan el valor mínimo, máximo, la suma y el promedio.
Count, DistinctCount	Cuentan filas con valores de campo no vacíos y valores de campo distintos.
Percentiles	Calculan uno o más percentiles.
TopRows	Devuelven las filas principales ordenadas en cada grupo como una subagregación.
GroupByField, GroupByComposite	Agrupan por el valor de un campo o por una combinación de campos.
GroupByRange, GroupByGeoDistance, GroupByFilter	Agrupan por rango numérico, distancia geográfica o condiciones de filtro.
GroupByHistogram, GroupByDateHistogram, GroupByGeoGrid	Crean histogramas numéricos, histogramas de fechas o grupos de cuadrícula GeoHash.

Importante

Los campos del índice de búsqueda utilizados para la agregación deben tener habilitadas las opciones de ordenamiento y agregación. Los tipos de campo compatibles varían según el tipo de agregación y agrupamiento. Es posible configurar hasta cinco agrupamientos en el mismo nivel. El recuento distinto, los percentiles y el agrupamiento por campo utilizan cálculos aproximados. Un gran número de agregaciones o agregaciones anidadas profundamente incrementa la complejidad y la latencia de la solicitud.

El siguiente ejemplo calcula el valor mínimo, máximo y promedio de price y agrupa las filas por category.

search_query = SearchQuery(
    MatchAllQuery(),
    limit=0,
    aggs=[
        Min("price", name="min_price"),
        Max("price", name="max_price"),
        Avg("price", name="avg_price"),
    ],
    group_bys=[
        GroupByField("category", name="by_category"),
    ],
)
response = client.search(
    "example_table",
    "example_index",
    search_query,
)
for result in response.agg_results:
    print(result.name, result.value)
for result in response.group_by_results:
    print(result.name, result.items)

Parámetros

Solicitud de búsqueda

El método search contiene los siguientes parámetros.

Nombre	Tipo	Descripción
table_name (obligatorio)	`str`	Nombre de la tabla de datos.
index_name (obligatorio)	`str`	Nombre del índice de búsqueda.
search_query (obligatorio)	`SearchQuery`	Condición de consulta y configuraciones comunes de la consulta.
columns_to_get (opcional)	`ColumnsToGet`	Configuración de columnas a devolver. Si no se especifica este parámetro, solo se devuelven las columnas de clave principal.
routing_keys (opcional)	`list`	Valores de clave principal de los campos de enrutamiento personalizados. Este parámetro no es necesario si no se ha configurado un enrutamiento personalizado.
timeout_s (opcional)	`int`	Tiempo de espera de la solicitud en segundos. Si no se especifica este parámetro, se utiliza el tiempo de espera a nivel de cliente.

Configuración de consulta

search_query es de tipo SearchQuery y contiene los siguientes parámetros relacionados con la agregación.

Nombre	Tipo	Descripción
query (obligatorio)	`Query`	Condición de consulta que determina el alcance de la agregación. Utilice `MatchAllQuery` para agregar todas las filas.
aggs (opcional)	`list[Agg]`	Lista de agregaciones métricas. Puede combinar agregaciones que tengan nombres diferentes.
group_bys (opcional)	`list[BaseGroupBy]`	Lista de agrupamientos. Puede combinar agrupamientos que tengan nombres diferentes.
limit (opcional)	`int`	Número de filas de consulta a devolver. Establezca este parámetro en `0` para recuperar únicamente los resultados de la agregación.

Agregaciones métricas

Agregue los siguientes objetos a search_query.aggs. field es el campo de agregación, name identifica el resultado y missing_value se utiliza cuando falta el campo. Si no se especifica missing_value, se ignoran las filas que carecen del campo.

Min, Max y Avg

Nombre	Tipo	Descripción
field (obligatorio)	`str`	Campo de agregación. Tipos compatibles: `Long`, `Double` y `Date`.
missing_value (opcional)	`str / int / float`	Valor que se utiliza cuando falta el campo.
name (opcional)	`str`	Nombre de la agregación. Valores predeterminados: `min`, `max` y `avg`, respectivamente.

Sum

Nombre	Tipo	Descripción
field (obligatorio)	`str`	Campo de agregación. Tipos compatibles: `Long` y `Double`.
missing_value (opcional)	`int / float`	Valor que se utiliza en la suma cuando falta el campo.
name (opcional)	`str`	Nombre de la agregación. Valor predeterminado: `sum`.

Count

Nombre	Tipo	Descripción
field (obligatorio)	`str`	Campo cuyas filas no vacías se cuentan. Tipos compatibles: `Long`, `Double`, `Boolean`, `Keyword`, `Date` y `GeoPoint`.
name (opcional)	`str`	Nombre de la agregación. Valor predeterminado: `count`.

DistinctCount

Nombre	Tipo	Descripción
field (obligatorio)	`str`	Campo cuyos valores distintos se cuentan. Tipos compatibles: `Long`, `Double`, `Boolean`, `Keyword`, `Date` y `GeoPoint`.
missing_value (opcional)	`str / int / float / bool`	Valor que se incluye en el recuento distinto cuando falta el campo.
name (opcional)	`str`	Nombre de la agregación. Valor predeterminado: `distinct_count`.

Percentiles

Nombre	Tipo	Descripción
field (obligatorio)	`str`	Campo de agregación. Tipos compatibles: `Long`, `Double` y `Date`.
percentiles_list (obligatorio)	`list[float]`	Percentiles a calcular, como `[50, 90, 99]`.
missing_value (opcional)	`str / int / float`	Valor que se utiliza cuando falta el campo.
name (opcional)	`str`	Nombre de la agregación. Valor predeterminado: `percentiles`.

TopRows

Nombre	Tipo	Descripción
limit (obligatorio)	`int`	Número máximo de filas a devolver de cada grupo.
sort (obligatorio)	`Sort`	Orden de clasificación de las filas en cada grupo.
name (opcional)	`str`	Nombre de la agregación. Valor predeterminado: `top_rows`.

Nota

DistinctCount es aproximado. Los resultados son cercanos al valor exacto por debajo de 10,000 valores distintos, y el error es de aproximadamente 2% con 100 millones de valores. Percentiles también es aproximado; los percentiles extremos suelen ser más precisos que la mediana. Utilice TopRows únicamente como subagregación de un agrupamiento.

Agrupamiento

Agregue los siguientes objetos a search_query.group_bys. Utilice sub_aggs y sub_group_bys para realizar subagregaciones métricas y subagrupamientos en cada grupo.

GroupByField

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	Campo de agrupamiento. Tipos compatibles: `Long`, `Double`, `Boolean`, `Keyword` y `Date`.
size (opcional)	`int`	Número de grupos a devolver. Valor predeterminado: `10`. Valor máximo: `2000`.
group_by_sort (opcional)	`list`	Reglas de ordenamiento de grupos. De forma predeterminada, los grupos se ordenan por recuento de filas en orden descendente. Son compatibles `GroupKeySort`, `RowCountSort` y `SubAggSort`.
sub_aggs (opcional)	`list[Agg]`	Subagregaciones métricas.
sub_group_bys (opcional)	`list[BaseGroupBy]`	Subagrupamientos.
name (opcional)	`str`	Nombre del agrupamiento. Valor predeterminado: `group_by_field`.

GroupByComposite

Nombre	Tipo	Descripción
sources (obligatorio)	`list[BaseGroupBy]`	Orígenes de agrupamiento multicampo. Puede especificar hasta 32 orígenes de tipo `GroupByField`, `GroupByHistogram` o `GroupByDateHistogram`.
size (opcional)	`int`	Número de grupos a devolver. Valor predeterminado: `10`. Valor máximo: `2000`.
next_token (opcional)	`bytes`	Token para la siguiente página de grupos. Omítalo en la primera solicitud.
suggested_size (opcional)	`int`	Límite flexible para escenarios de cómputo de alto throughput. No lo especifique junto con `size`.
sub_aggs (opcional)	`list[Agg]`	Subagregaciones métricas.
sub_group_bys (opcional)	`list[BaseGroupBy]`	Subagrupamientos. `GroupByComposite` no puede ser un subgrupo de otro agrupamiento.
name (opcional)	`str`	Nombre del agrupamiento. Valor predeterminado: `group_by_composite`.

GroupByRange

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	Campo de agrupamiento. Tipos compatibles: `Long` y `Double`.
ranges (obligatorio)	`list[tuple]`	Rangos cerrados por la izquierda y abiertos por la derecha, como `[(0, 100), (100, 200)]`.
sub_aggs (opcional)	`list[Agg]`	Subagregaciones métricas.
sub_group_bys (opcional)	`list[BaseGroupBy]`	Subagrupamientos.
name (opcional)	`str`	Nombre del agrupamiento. Valor predeterminado: `group_by_range`.

GroupByGeoDistance

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	Campo de agrupamiento `GeoPoint`.
origin (obligatorio)	`GeoPoint`	Punto central. Los parámetros del constructor son latitud seguida de longitud.
ranges (obligatorio)	`list[tuple]`	Rangos de distancia en metros. Cada rango es cerrado por la izquierda y abierto por la derecha.
sub_aggs (opcional)	`list[Agg]`	Subagregaciones métricas.
sub_group_bys (opcional)	`list[BaseGroupBy]`	Subagrupamientos.
name (opcional)	`str`	Nombre del agrupamiento. Valor predeterminado: `group_by_geo_distance`.

GroupByFilter

Nombre	Tipo	Descripción
filters (obligatorio)	`list[Query]`	Condiciones de filtro. El orden de los resultados coincide con el orden de las condiciones.
sub_aggs (opcional)	`list[Agg]`	Subagregaciones métricas.
sub_group_bys (opcional)	`list[BaseGroupBy]`	Subagrupamientos.
name (opcional)	`str`	Nombre del agrupamiento. Valor predeterminado: `group_by_filter`.

GroupByHistogram

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	Campo de agrupamiento. Tipos compatibles: `Long` y `Double`.
interval (obligatorio)	`int / float`	Intervalo del histograma numérico.
field_range (obligatorio)	`FieldRange`	Rango de agregación. `(max-min)/interval` no puede exceder `2000`.
missing_value (opcional)	`int / float`	Valor que se utiliza en el histograma cuando falta el campo.
min_doc_count (opcional)	`int`	Recuento mínimo de filas para un bucket. Los buckets con menos filas no se devuelven.
group_by_sort (opcional)	`list`	Reglas de ordenamiento de grupos.
sub_aggs (opcional)	`list[Agg]`	Subagregaciones métricas.
sub_group_bys (opcional)	`list[BaseGroupBy]`	Subagrupamientos.
name (opcional)	`str`	Nombre del agrupamiento. Valor predeterminado: `group_by_histogram`.

GroupByDateHistogram

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	Campo de agrupamiento `Date`.
interval (obligatorio)	`DateTimeValue`	Intervalo de fecha u hora, compuesto por un valor y `DateTimeUnit`.
field_range (obligatorio)	`FieldRange`	Rango de agregación. El servidor requiere este parámetro aunque el constructor de Python permita omitirlo.
missing (opcional)	`str`	Valor de fecha que se utiliza en el histograma cuando falta el campo.
min_doc_count (opcional)	`int`	Recuento mínimo de filas para un bucket. Los buckets con menos filas no se devuelven.
time_zone (opcional)	`str`	Zona horaria en formato `+hh:mm` o `-hh:mm`, como `+08:00`.
group_by_sort (opcional)	`list`	Reglas de ordenamiento de grupos.
offset (opcional)	`DateTimeValue`	Desplazamiento del límite del bucket respecto al origen predeterminado.
sub_aggs (opcional)	`list[Agg]`	Subagregaciones métricas.
sub_group_bys (opcional)	`list[BaseGroupBy]`	Subagrupamientos.
name (opcional)	`str`	Nombre del agrupamiento. Valor predeterminado: `group_by_date_histogram`.

GroupByGeoGrid

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	Campo de agrupamiento `GeoPoint`.
precision (obligatorio)	`GeoHashPrecision`	Precisión de la cuadrícula GeoHash. Un número de enumeración mayor representa una cuadrícula más pequeña.
size (opcional)	`int`	Número de grupos de cuadrícula a devolver.
sub_aggs (opcional)	`list[Agg]`	Subagregaciones métricas.
sub_group_bys (opcional)	`list[BaseGroupBy]`	Subagrupamientos.
name (opcional)	`str`	Nombre del agrupamiento. Valor predeterminado: `group_by_geo_grid`.

Nota

GroupByComposite requiere Tablestore SDK for Python 6.4.4 o posterior. Si existen muchos grupos, especifique size y pagine mediante next_token de cada resultado hasta que el token esté vacío.

Columnas de retorno

columns_to_get es de tipo ColumnsToGet y contiene los siguientes parámetros.

Nombre	Tipo	Descripción
column_names (opcional)	`list[str]`	Nombres de las columnas de atributos a devolver. Especifique este parámetro solo cuando `return_type` sea `SPECIFIED`.
return_type (opcional)	`ColumnReturnType`	Modo de columna de retorno. `NONE` (predeterminado) devuelve solo columnas de clave principal; `SPECIFIED` devuelve las columnas de atributos especificadas; `ALL` devuelve todas las columnas de atributos de la tabla; y `ALL_FROM_INDEX` devuelve todos los campos almacenados en el índice.

Respuesta

El método search devuelve SearchResponse. La siguiente tabla describe los campos principales.

Campo	Tipo	Descripción
rows	`list[Row]`	Filas devueltas por la consulta. El número no excede `limit`.
next_token	`bytes`	Token para la siguiente página. Un valor vacío indica que no hay más datos disponibles.
total_count	`int`	Número de filas coincidentes. El valor depende de `get_total_count`.
is_all_succeed	`bool`	Indica si se consultaron todas las particiones del índice. Si el valor es `False`, se devuelven resultados parciales.
agg_results	`list[AggResult]`	Resultados de la agregación métrica. Este campo está vacío si no se configura `aggs`.
group_by_results	`list[GroupByResult]`	Resultados del agrupamiento. Este campo está vacío si no se configura `group_bys`.
search_hits	`list[SearchHit]`	Coincidencias de búsqueda, que incluyen información extendida como filas, puntuaciones de relevancia y resaltados.

Cada elemento en agg_results usa name y value para identificar una agregación y su valor. Cada elemento en group_by_results usa name y items para devolver claves de grupo, recuentos de filas, subagregaciones y subagrupamientos. Un resultado de GroupByComposite también contiene source_group_by_names y next_token para lecturas continuas. Las keys de cada grupo son una lista de cadenas alineada con sources; un valor de campo faltante se representa mediante None.

Respuesta compatible con tuplas

A partir de Tablestore SDK for Python 5.2.0, las API de búsqueda devuelven objetos de respuesta en lugar de tuplas. La versión 5.1.0 y anteriores devuelven tuplas directamente. En la versión 5.2.1 y posteriores, puede llamar a SearchResponse.v1_response() para obtener una tupla compatible con versiones anteriores. Para código nuevo, acceda directamente a los atributos de SearchResponse para evitar errores de desempaquetado si se extienden los campos de respuesta.

(
    rows,
    next_token,
    total_count,
    is_all_succeed,
    agg_results,
    group_by_results,
    search_hits,
) = response.v1_response()

Ejemplos

Paginar un agrupamiento multicampo

El siguiente ejemplo agrupa por category y price, y devuelve dos grupos por página.

sources = [
    GroupByField("category", name="category_source"),
    GroupByField("price", name="price_source"),
]
next_token = None
all_items = []

while True:
    group_by = GroupByComposite(
        sources,
        size=2,
        next_token=next_token,
        name="by_category_and_price",
    )
    response = client.search(
        "example_table",
        "example_index",
        SearchQuery(MatchAllQuery(), limit=0, group_bys=[group_by]),
    )
    result = response.group_by_results[0]
    all_items.extend(result.items)
    next_token = result.next_token
    if not next_token:
        break

for item in all_items:
    print(item.keys, item.row_count)

Crear un histograma de fechas y una cuadrícula geográfica

El siguiente ejemplo crea un histograma de fechas diario y agrupa ubicaciones en cuadrículas GeoHash de aproximadamente 39 km por 19 km.

group_bys = [
    GroupByDateHistogram(
        "event_date",
        DateTimeValue(1, DateTimeUnit.DAY),
        field_range=FieldRange("2026-08-01", "2026-08-04"),
        name="by_day",
    ),
    GroupByGeoGrid(
        "location",
        GeoHashPrecision.GHP_39KM_19KM_4,
        name="by_geo_grid",
    ),
]
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), limit=0, group_bys=group_bys),
)
for result in response.group_by_results:
    print(result.name, result.items)