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

Utilice Tablestore SDK for Python para realizar búsquedas de texto completo en campos Text o Keyword y devolver los datos coincidentes.

Requisitos previos

Instale Tablestore SDK for Python e inicialice un cliente.

Descripción

Una consulta de coincidencia busca en campos Text o Keyword (consulte String types). En un campo Text, el analizador del campo tokeniza el texto de la consulta, y operator o minimum_should_match determina qué tokens deben coincidir. En un campo Keyword, el texto de la consulta no se tokeniza. Esta consulta no requiere que los tokens aparezcan de forma consecutiva ni en el mismo orden del texto buscado. Para coincidir con el orden y la posición de los tokens, utilice una Match phrase query.

MatchQuery(
    field_name,
    text,
    minimum_should_match=None,
    operator=None,
    weight=None,
)

A continuación se muestra un ejemplo que consulta filas donde el campo description contiene tanto el token tablestore como el token durable.

query = MatchQuery(
    "description",
    "tablestore durable",
    operator=QueryOperator.AND,
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(
        query,
        sort=Sort([ScoreSort()]),
        limit=10,
        get_total_count=True,
    ),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
for hit in response.search_hits:
    print(hit.score, hit.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 comunes de la consulta.
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`	Los 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`	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 en `MatchQuery`.
sort (opcional)	`Sort`	El orden de clasificación de los resultados. Para obtener más información, consulte Sort and paginate results.
get_total_count (opcional)	`bool`	Especifica si se debe devolver el número total de filas coincidentes. Valor predeterminado: `False`. Establecer este parámetro en `True` incrementa la sobrecarga de la consulta.
next_token (opcional)	`bytes`	El token de paginación. Pase el valor de `next_token` de la respuesta anterior para recuperar la siguiente página.
offset (opcional)	`int`	El desplazamiento desde el cual comienza la consulta. 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 ninguna fila.
aggs (opcional)	`list[Agg]`	Las configuraciones de agregación de métricas. 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. 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 coincidencia

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

Nombre	Tipo	Descripción
field_name (obligatorio)	`str`	El nombre del campo `Text` o `Keyword` que se va a consultar.
text (obligatorio)	`str`	El texto de la consulta. Se tokeniza para un campo `Text` y no se tokeniza para un campo `Keyword`.
minimum_should_match (opcional)	`int`	El número mínimo de tokens de la consulta que deben coincidir cuando `operator` es `OR`.
operator (opcional)	`QueryOperator`	El modo de combinación de tokens. `OR` (predeterminado) coincide con cualquier token, mientras que `AND` requiere que todos los tokens coincidan.
weight (opcional)	`float`	El peso de la consulta, que debe ser un número de punto flotante positivo. Valor predeterminado: `1.0`. Afecta las puntuaciones de relevancia, pero no la coincidencia en sí.

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 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 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]`	Las filas devueltas por la consulta. La cantidad no excede el valor de `limit`.
next_token	`bytes`	El token para la siguiente página. Un valor vacío indica que no hay más datos disponibles.
total_count	`int`	El 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]`	Los resultados de la agregación de métricas. Este campo está vacío si no se configura `aggs`.
group_by_results	`list[GroupByResult]`	Los resultados del agrupamiento. Este campo está vacío si no se configura `group_bys`.
search_hits	`list[SearchHit]`	Los aciertos de la búsqueda, que incluyen información extendida como filas, puntuaciones de relevancia y resaltados.

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 amplían los campos de la respuesta.

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

Ejemplos

Especificar el número mínimo de tokens coincidentes

El siguiente ejemplo requiere que coincidan como mínimo dos tokens del texto de consulta tokenizado.

query = MatchQuery(
    "description",
    "tablestore durable cloud",
    operator=QueryOperator.OR,
    minimum_should_match=2,
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
)
print(response.rows)