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

Utilice Tablestore SDK for Python para ejecutar una consulta de rango en un índice de búsqueda y filtrar datos según los límites de valor de un campo. Puede controlar si cada límite se incluye en la consulta.

Requisitos previos

Instale Tablestore SDK for Python e inicialice un cliente.

Descripción

Una consulta de rango en un índice de búsqueda coincide con las filas cuyos valores de campo se encuentran dentro de un intervalo especificado. Puede definir únicamente el límite inferior, únicamente el límite superior o ambos; sin embargo, debe especificar como mínimo uno de ellos. En el caso de un campo Text, una fila coincide si alguno de sus tokens se encuentra dentro del intervalo. Al invocar el método search, establezca el tipo de consulta como RangeQuery.

RangeQuery(field_name, range_from=None, range_to=None, include_lower=True, include_upper=False)

A continuación se muestra un ejemplo que consulta las filas donde el campo price se encuentra en el intervalo cerrado por la izquierda y abierto por la derecha [100, 500). La consulta devuelve hasta 10 filas y el número total de filas coincidentes.

query = RangeQuery(
    "price",
    range_from=100,
    range_to=500,
    include_lower=True,
    include_upper=False,
)
search_query = SearchQuery(
    query,
    limit=10,
    get_total_count=True,
)
response = client.search(
    "example_table",
    "example_index",
    search_query,
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.total_count)
for row in response.rows:
    print(row)

Parámetros

Solicitud de búsqueda

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

Nombre	Tipo	Descripción
table_name (obligatorio)	`str`	El nombre de la tabla de datos.
index_name (obligatorio)	`str`	El nombre del índice de búsqueda.
search_query (obligatorio)	`SearchQuery`	La condición de consulta y las configuraciones generales de la misma.
columns_to_get (opcional)	`ColumnsToGet`	La 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`	La lista de valores de clave primaria para los campos de enrutamiento personalizado. No es necesario especificar este parámetro si no se ha configurado el enrutamiento personalizado.
timeout_s (opcional)	`int`	El tiempo de espera de la solicitud en segundos. Si no se especifica este parámetro, se utiliza el tiempo de espera definido a nivel de cliente.

Configuración de la consulta

search_query es de tipo SearchQuery e incluye los siguientes parámetros.

Nombre	Tipo	Descripción
query (obligatorio)	`Query`	La condición de consulta. Establezca este parámetro como `RangeQuery`.
sort (opcional)	`Sort`	El orden de clasificación de los resultados de la consulta. Para obtener más información, consulte Sort and paginate results.
get_total_count (opcional)	`bool`	Indica si se debe devolver el número total de filas coincidentes. Valor predeterminado: `False`. Establecer este parámetro como `True` incrementa la sobrecarga de la consulta.
next_token (opcional)	`bytes`	El token de paginación. Establezca este parámetro con el valor `next_token` de la respuesta anterior para recuperar la siguiente página. Para obtener más información, consulte Sort and paginate results.
offset (opcional)	`int`	El desplazamiento desde el cual comienza la consulta actual. Utilice este parámetro para una paginación superficial.
limit (opcional)	`int`	El número máximo de filas a devolver. Si este parámetro se establece en `0`, no se devuelve ningún dato de fila.
aggs (opcional)	`list[Agg]`	Las configuraciones de agregación. Para obtener más información, consulte Aggregation.
group_bys (opcional)	`list[BaseGroupBy]`	Las configuraciones de agrupamiento. Para obtener más información, consulte Aggregation.
collapse_field (opcional)	`Collapse`	La configuración de colapso de resultados, que elimina duplicados con base en un campo específico. Para obtener más información, consulte Collapse query results.
highlight (opcional)	`Highlight`	La configuración de resumen y resaltado para campos `Text`. Para obtener más información, consulte Summary and highlighting.

Condición de consulta

search_query.query es de tipo RangeQuery e incluye los siguientes parámetros.

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	El nombre del campo indexado que se va a consultar. Las consultas de rango admiten campos `Long`, `Double`, `Boolean`, `Keyword`, `Text` y `Date`, así como campos secundarios de objetos JSON. En el caso de un campo `Text`, una fila coincide si alguno de sus tokens se encuentra dentro del intervalo.
range_from (opcional)	`str / int / float / bool`	El límite inferior. Debe especificar como mínimo uno de los parámetros `range_from` o `range_to`.
range_to (opcional)	`str / int / float / bool`	El límite superior. Debe especificar como mínimo uno de los parámetros `range_from` o `range_to`.
include_lower (opcional)	`bool`	Indica si se incluye el límite inferior. Valor predeterminado: `True`.
include_upper (opcional)	`bool`	Indica si se incluye el límite superior. Valor predeterminado: `False`.

Columnas de retorno

columns_to_get es de tipo ColumnsToGet e incluye los siguientes parámetros.

Nombre	Tipo	Descripción
column_names (opcional)	`list[str]`	Los nombres de las columnas de atributos que se van a devolver. Especifique este parámetro únicamente cuando `return_type` sea `SPECIFIED`.
return_type (opcional)	`ColumnReturnType`	El modo de retorno de columnas. `NONE` (predeterminado) devuelve solo las columnas de clave primaria; `SPECIFIED` devuelve las columnas de atributos indicadas en `column_names`; `ALL` devuelve todas las columnas de atributos de la tabla; y `ALL_FROM_INDEX` devuelve todas las columnas de atributos indexadas.

Respuesta

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

Campo	Tipo	Descripción
rows	`list[Row]`	Las filas devueltas por la consulta actual. El número de filas no supera el valor de `limit`.
next_token	`bytes`	El token para la siguiente página. Si este campo no está vacío, páselo a la siguiente solicitud para continuar la lectura.
total_count	`int`	El número de filas coincidentes. Este valor depende de la configuración 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 y `total_count` podría ser menor que el número real de filas coincidentes.
agg_results	`list[AggResult]`	Los resultados de agregación. Este campo está vacío si no se configuran las opciones de `aggs`.
group_by_results	`list[GroupByResult]`	Los resultados de agrupamiento. Este campo está vacío si no se configuran las opciones de `group_bys`.
search_hits	`list[SearchHit]`	Los aciertos de búsqueda, que incluyen información extendida como puntuaciones de relevancia, resaltados y filas secundarias coincidentes.

Respuesta compatible con tuplas

A partir de la versión 5.2.0 de Tablestore SDK for Python, las API de búsqueda devuelven objetos de respuesta en lugar de tuplas. Las versiones 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 y evite errores de desempaquetado en caso de que se amplíen los campos de respuesta.

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