Todos os produtos
Search

Este produto

    Tablestore:Consulta de correspondência

    Central de documentação

    Tablestore:Consulta de correspondência

    Última atualização: Jul 03, 2026

    A consulta de correspondência permite consultar dados em uma tabela com base em correspondências aproximadas. O Tablestore tokeniza os valores nas colunas TEXT e as palavras-chave usadas na consulta conforme o tipo de analisador especificado. Assim, o Tablestore executa a consulta com base nos tokens gerados. Para colunas que utilizam tokenização difusa, recomenda-se o uso da consulta de frase correspondente (match phrase query) para garantir alto desempenho.

    Pré-requisitos

    Parâmetros

    Parâmetro

    Descrição

    field_name

    Nome da coluna a ser consultada.

    A consulta de correspondência aplica-se a colunas do tipo TEXT.

    text

    Palavra-chave usada para corresponder ao valor da coluna durante a consulta.

    Se a coluna consultada for do tipo TEXT, a palavra-chave será dividida em vários tokens conforme o analisador definido na criação do índice de pesquisa. Caso nenhum analisador seja especificado, o sistema aplica a tokenização por palavra única por padrão.

    Por exemplo, se a coluna alvo for TEXT, o analisador for configurado para tokenização por palavra única e a palavra-chave de busca for "this is", os resultados podem incluir "..., this is tablestore", "is this tablestore", "tablestore is cool", "this" e "is".

    query

    Tipo da consulta. Defina este parâmetro como MatchQuery.

    table_name

    Nome da tabela de dados.

    index_name

    Nome do índice de pesquisa.

    limit

    Número máximo de linhas retornadas pela consulta atual.

    Para obter apenas a contagem de linhas que atendem aos critérios, sem recuperar os dados específicos, defina o parâmetro limit como 0.

    operator

    Operador lógico. Por padrão, o sistema utiliza OR. Esse operador considera que uma linha atende à consulta quando o valor da coluna contém pelo menos o número mínimo de tokens correspondentes.

    Ao definir o parâmetro operator como AND, a linha só atenderá à condição se o valor da coluna contiver todos os tokens.

    minimum_should_match

    Quantidade mínima de tokens correspondentes que o valor da coluna deve conter.

    O sistema retorna uma linha somente se o valor da coluna consultada possuir pelo menos o número mínimo especificado de palavras-chave tokenizadas correspondentes.

    Nota

    O parâmetro minimum_should_match exige o uso do operador lógico OR.

    get_total_count

    Define se o total de linhas correspondentes deve ser retornado. O valor padrão é false, indicando que a contagem total não será incluída na resposta.

    Habilitar essa opção (true) pode reduzir o desempenho da consulta.

    columns_to_get

    Determina quais colunas retornar para cada linha correspondente.

    • Com return_type definido como ColumnReturnType.SPECIFIED, utilize o campo column_names para indicar as colunas desejadas.

    • ColumnReturnType.ALL retorna todas as colunas disponíveis.

    • ColumnReturnType.NONE restringe o retorno apenas às colunas de chave primária.

    Exemplos

    Os exemplos abaixo demonstram como consultar linhas em que o valor da coluna Col_Keyword corresponde aproximadamente a 'this is'.

    • Executar consulta de correspondência com Tablestore SDK for Python V5.2.1 ou posterior

      Ao utilizar o Tablestore SDK for Python V5.2.1 ou posterior, a resposta padrão é um objeto SearchResponse. O código a seguir ilustra uma requisição de exemplo:

      query = MatchQuery('Col_Keyword', 'this is')
search_response = client.search(
    '<TABLE_NAME>', '<SEARCH_INDEX_NAME>', 
    SearchQuery(query, limit=100, get_total_count=True), 
    ColumnsToGet(return_type=ColumnReturnType.ALL)
)
print('request_id : %s' % search_response.request_id)
print('is_all_succeed : %s' % search_response.is_all_succeed)
print('total_count : %s' % search_response.total_count)
print('rows : %s' % search_response.rows)

# # If deep paging is required, we recommend that you use the next_token parameter because this method has no limits on the paging depth. 
# all_rows = []
# next_token = None
# # first round
# search_response = client.search(
#     '<TABLE_NAME>', '<SEARCH_INDEX_NAME>',
#     SearchQuery(query, next_token=next_token, limit=100, get_total_count=True),
#     columns_to_get=ColumnsToGet(return_type=ColumnReturnType.ALL))
# all_rows.extend(search_response.rows)
# 
# # loop
# while search_response.next_token:
#     search_response = client.search(
#         '<TABLE_NAME>', '<SEARCH_INDEX_NAME>',
#         SearchQuery(query, next_token=search_response.next_token, limit=100, get_total_count=True),
#         columns_to_get=ColumnsToGet(return_type=ColumnReturnType.ALL))
#     all_rows.extend(search_response.rows)
# print('Total rows:%s' % len(all_rows))

      Para obter resultados no formato Tuple, utilize o seguinte modelo de requisição:

      query = MatchQuery('Col_Keyword', 'this is')
rows, next_token, total_count, is_all_succeed, agg_results, group_by_results = client.search(
    '<TABLE_NAME>', '<SEARCH_INDEX_NAME>', 
    SearchQuery(query, limit=100, get_total_count=True), 
    ColumnsToGet(return_type=ColumnReturnType.ALL)
).v1_response()

    • Executar consulta de correspondência com versões anteriores à 5.2.1 do Tablestore SDK for Python

      Em versões do Tablestore SDK for Python anteriores à 5.2.1, o retorno padrão da consulta é do tipo TUPLE. Veja abaixo um exemplo de requisição:

      query = MatchQuery('Col_Keyword', 'this is')
rows, next_token, total_count, is_all_succeed = client.search(
    '<TABLE_NAME>', '<SEARCH_INDEX_NAME>', 
    SearchQuery(query, limit=100, get_total_count=True), 
    ColumnsToGet(return_type=ColumnReturnType.ALL)
)

    FAQ

    Referências