Sort and paginate results - Tablestore SDK for Python - Tablestore

Utilice Tablestore SDK for Python para controlar el orden de los resultados del índice de búsqueda y paginarlos mediante offset o next_token.

Requisitos previos

Instale Tablestore SDK for Python e inicialice un cliente.

Descripción

Los índices de búsqueda admiten preordenamiento de índice y ordenamiento en tiempo de consulta. Al crear un índice de búsqueda, utilice index_sort para especificar el orden predeterminado. Si no se especifica index_sort, las filas se ordenan por clave primaria. El preordenamiento de índice solo admite PrimaryKeySort y FieldSort, y no es compatible con índices que contienen un campo Nested. Después de la creación, puede actualizar dinámicamente el esquema para modificar el preordenamiento del índice. Durante la consulta, utilice SearchQuery.sort para especificar ScoreSort, PrimaryKeySort, FieldSort o GeoDistanceSort, o bien combine varios ordenadores según el orden de la lista. A excepción de las claves primarias, los campos de ordenamiento deben tener habilitadas las opciones de ordenamiento y agregación al momento de crear el índice.

Método de paginación	Descripción
limit y offset	Utilícelo cuando los resultados no superen las 100,000 filas y necesite saltar a una posición específica. La suma de `limit + offset` no puede exceder `100000`.
next_token	Apropiado para paginación profunda o lectura secuencial de todos los resultados. La profundidad de paginación no está sujeta al límite de 100,000 filas, pero las páginas solo pueden leerse de forma secuencial.

El siguiente ejemplo devuelve las primeras 10 filas ordenadas por score en orden descendente y luego por clave primaria en orden ascendente.

sort = Sort([
    FieldSort("score", SortOrder.DESC),
    PrimaryKeySort(SortOrder.ASC),
])
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), sort=sort, limit=10),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)

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 primaria.
routing_keys (opcional)	`list`	Valores de clave primaria de los campos de enrutamiento personalizado. Este parámetro no es necesario si no se ha configurado el 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 de ordenamiento y paginación.

Nombre	Tipo	Descripción
query (obligatorio)	`Query`	Condición de consulta.
sort (opcional)	`Sort`	Configuración de ordenamiento en tiempo de consulta. Si se omite, se utiliza el preordenamiento del índice. No lo especifique cuando utilice `next_token`.
offset (opcional)	`int`	Desplazamiento. Valor predeterminado: `0`. No lo especifique cuando utilice `next_token`.
limit (opcional)	`int`	Número máximo de filas a devolver. Valor predeterminado: `10`. El máximo es `100` si alguna columna de retorno debe leerse desde la tabla, y `1000` si todas las columnas de retorno se leen desde el índice de búsqueda.
next_token (opcional)	`bytes`	Token de paginación. Omítalo en la primera solicitud y utilice el `next_token` de la respuesta anterior en las solicitudes subsiguientes.
get_total_count (opcional)	`bool`	Especifica si se debe devolver el número total de filas coincidentes. Valor predeterminado: `False`.

Configuración de ordenamiento

search_query.sort es de tipo Sort y contiene el siguiente parámetro.

Nombre	Tipo	Descripción
sorters (obligatorio)	`list[Sorter]`	Lista de ordenadores. El orden de la lista determina la prioridad del ordenamiento multinivel. Los tipos de ordenador compatibles son `ScoreSort`, `PrimaryKeySort`, `FieldSort` y `GeoDistanceSort`.

Ordenamiento por puntuación de relevancia

Si search_query.sort.sorters[] es de tipo ScoreSort, las filas se ordenan por puntuación de relevancia. ScoreSort contiene el siguiente parámetro.

Nombre	Tipo	Descripción
sort_order (opcional)	`SortOrder`	Orden de clasificación. Valor predeterminado: `DESC`. Configure explícitamente `ScoreSort` para ordenar por puntuación de relevancia.

Ordenamiento por clave primaria

Si search_query.sort.sorters[] es de tipo PrimaryKeySort, las filas se ordenan por clave primaria. PrimaryKeySort contiene el siguiente parámetro.

Nombre	Tipo	Descripción
sort_order (opcional)	`SortOrder`	Orden de clasificación. Valor predeterminado: `ASC`.

Ordenamiento por campo

Si search_query.sort.sorters[] es de tipo FieldSort, las filas se ordenan por valor de campo. FieldSort contiene los siguientes parámetros.

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	Nombre del campo de ordenamiento. El campo debe tener habilitadas las opciones de ordenamiento y agregación.
sort_order (opcional)	`SortOrder`	Orden de clasificación. Valor predeterminado: `ASC`.
sort_mode (opcional)	`SortMode`	Modo de selección de valores para un campo multivalor: `MIN`, `MAX` o `AVG`.
nested_filter (opcional)	`NestedFilter`	Configuración de ordenamiento de campos secundarios Nested, que incluye la ruta Nested y una consulta que selecciona las filas secundarias utilizadas para el ordenamiento.

Ordenamiento por distancia geográfica

Si search_query.sort.sorters[] es de tipo GeoDistanceSort, las filas se ordenan según la distancia entre un punto geográfico y los puntos objetivo. GeoDistanceSort contiene los siguientes parámetros.

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	Nombre del campo de ordenamiento GeoPoint.
points (obligatorio)	`list[str]`	Puntos objetivo en formato `latitude,longitude`.
sort_order (opcional)	`SortOrder`	`ASC` ordena del más cercano al más lejano, y `DESC` ordena del más lejano al más cercano.
sort_mode (opcional)	`SortMode`	Modo de selección de valores cuando existen múltiples distancias: `MIN`, `MAX` o `AVG`.
geo_distance_type (opcional)	`GeoDistanceType`	Método de cálculo de distancia. `ARC` (predeterminado) utiliza un modelo esférico, mientras que `PLANE` emplea un modelo plano.
nested_filter (opcional)	`NestedFilter`	Configuración de ordenamiento de campos secundarios Nested.

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 únicamente cuando `return_type` sea `SPECIFIED`.
return_type (opcional)	`ColumnReturnType`	Modo de columnas de retorno. `NONE` (predeterminado) devuelve solo columnas de clave primaria; `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. La cantidad no excede el valor de `limit`.
next_token	`bytes`	Token para la página siguiente. 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 agregación de métricas. Este campo está vacío si no se configura `aggs`.
group_by_results	`list[GroupByResult]`	Resultados de 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.

Un valor vacío en next_token también puede indicar que la consulta no tiene un orden de clasificación determinista. total_count representa el número total de filas coincidentes, no la cantidad de filas de la página actual.

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 con el fin de evitar errores de desempaquetado si se amplían los campos de respuesta.

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

Ejemplos

Ordenar por distancia geográfica

El siguiente ejemplo devuelve resultados ordenados del más cercano al más lejano según la distancia esférica entre location y 30.25,120.16.

sort = Sort([
    GeoDistanceSort(
        "location",
        ["30.25,120.16"],
        sort_order=SortOrder.ASC,
        sort_mode=SortMode.MIN,
        geo_distance_type=GeoDistanceType.ARC,
    )
])
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), sort=sort, limit=10),
)
print(response.rows)

Paginar mediante next_token

Especifique el orden de clasificación en la primera solicitud. En las solicitudes posteriores, pase únicamente el next_token de la respuesta anterior y la misma condición de consulta hasta que el token esté vacío.

query = MatchAllQuery()
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, sort=Sort([PrimaryKeySort()]), limit=100),
)
all_rows = list(response.rows)

while response.next_token:
    response = client.search(
        "example_table",
        "example_index",
        SearchQuery(query, next_token=response.next_token, limit=100),
    )
    all_rows.extend(response.rows)

print(len(all_rows))

Importante

Al paginar mediante next_token, no especifique offset, ya que no es posible saltar páginas directamente. Para retroceder, almacene en caché el token utilizado para cada página y vuelva a consultar con el token correspondiente a la página deseada. Un índice de búsqueda que contiene un campo Nested carece de preordenamiento de índice. Especifique explícitamente sort en la primera solicitud; de lo contrario, el servidor no devolverá next_token.

Tablestore:Sort and paginate results