Todos os produtos
Search
Central de documentação

Tablestore:Consulta de correspondência

Última atualização: Sep 29, 2026

A consulta de correspondência realiza uma busca aproximada nos dados de uma tabela. O Tablestore usa o tokenizador configurado para dividir os valores das colunas Text e a consulta de pesquisa em tokens e, em seguida, busca por esses tokens. Para executar consultas fuzzy de alto desempenho em colunas Text que usam tokenização fuzzy, use uma consulta de frase de correspondência.

Cenários

A consulta de correspondência localiza dados que contêm uma frase específica. Quando usada com tokenização, possibilita a indexação de texto completo. Isso é útil em cenários como análise de dados, pesquisa de conteúdo, gerenciamento de conhecimento, análise de mídias sociais, análise de logs, sistemas de chat com IA e revisões de conformidade. Por exemplo, é possível filtrar rapidamente produtos em uma plataforma de e-commerce cujos títulos, descrições ou rótulos contenham palavras-chave inseridas por um usuário. Também é possível localizar rapidamente mensagens de erro ou operações anômalas nos logs.

Visão geral do funcionamento

A consulta de correspondência realiza uma busca aproximada nos dados de uma tabela. Por exemplo, considere uma linha com uma coluna title do tipo Text que possui o valor "Hángzhōu Xīhú Fēngjǐngqū". Se essa coluna usar tokenização de palavra única e a consulta de pesquisa for "hú fēng", a linha é encontrada.

Ao usar uma consulta de correspondência, especifique a coluna de destino e a consulta de pesquisa. Uma linha atende à condição da consulta se qualquer um dos tokens da consulta de pesquisa existir na coluna especificada.

Também é possível configurar parâmetros como o número mínimo de correspondências, o peso da consulta, as colunas a serem retornadas, a opção de retornar o número total de linhas correspondidas e o método de ordenação do conjunto de resultados.

Operações da API

As operações da API para uma consulta de correspondência são Search ou ParallelScan. O tipo específico de consulta é MatchQuery.

Parâmetros

Parâmetro

Descrição

fieldName

A coluna de destino.

A consulta de correspondência pode ser aplicada a colunas do tipo Text.

text

A consulta de pesquisa, ou seja, o valor a ser buscado.

Para colunas Text, a consulta de pesquisa é dividida em vários tokens com base no tipo de tokenizador definido na criação do índice de pesquisa. Se nenhum tokenizador tiver sido definido, a tokenização de palavra única é usada por padrão.

Por exemplo, em uma coluna Text com tokenização de palavra única, a consulta de pesquisa "this is" pode corresponder a "..., this is tablestore", "is this tablestore", "tablestore is cool", "this" e "is".

query

Defina o tipo de consulta como matchQuery.

offset

A posição inicial da consulta.

limit

O número máximo de resultados a serem retornados na consulta.

Para obter apenas a contagem de linhas sem retornar dados, defina limit como 0. Essa configuração não retorna nenhuma linha.

minimumShouldMatch

O número mínimo de correspondências.

Uma linha é retornada somente se o valor na coluna fieldName contiver pelo menos o número mínimo de tokens correspondentes.

Nota

minimumShouldMatch deve ser usado com o operador lógico OR.

operator

O operador lógico. O padrão é OR, o que significa que uma linha atende à condição da consulta se alguns dos tokens corresponderem.

Ao definir operator como AND, uma linha atenderá à condição da consulta somente se todos os tokens estiverem presentes no valor da coluna.

getTotalCount

Especifica se o número total de linhas correspondidas deve ser retornado. O padrão é false, o que significa que a contagem total não é retornada.

Retornar o número total de linhas correspondidas pode afetar o desempenho da consulta.

weight

O peso da consulta, usado para ordenação baseada em pontuação em cenários de índice de texto completo. Este parâmetro especifica o peso para o cálculo da pontuação de uma coluna. Um valor maior resulta em uma pontuação mais alta. O valor deve ser um número de ponto flutuante positivo.

Este parâmetro não afeta o número de resultados retornados, apenas as pontuações deles.

tableName

O nome da tabela de dados.

indexName

O nome do índice de pesquisa.

columnsToGet

Especifica se todas as colunas devem ser retornadas. Isso inclui as configurações returnAll e columns.

returnAll é false por padrão, o que significa que nem todas as colunas são retornadas. Nesse caso, use columns para especificar quais colunas retornar. Se nenhuma coluna for especificada, apenas as colunas de chave primária serão retornadas.

Ao definir returnAll como true, todas as colunas são retornadas.

Observações

O Search Index oferece apenas a pontuação de relevância BM25 básica e não oferece suporte a modelos de relevância personalizados.

Uso

É possível executar uma consulta de correspondência usando o console, a interface de linha de comando (CLI) ou um kit de desenvolvimento de software (SDK). Antes de começar, conclua as seguintes etapas preparatórias.

Usar o console

  1. Acesse a aba Index Management.

    1. Faça login no Table Store console.

    2. Na barra de navegação superior, selecione um grupo de recursos e uma região.

    3. Na página Overview, clique no nome da instância ou clique em Instance Management na coluna Actions.

    4. Na aba Instance Details, na aba Data Table List, clique no nome da tabela de dados ou clique em Index Management na coluna Actions.

  2. Na aba Index Management, localize o Search Index de destino e clique em Search na coluna Actions.

  3. Na caixa de diálogo Search, pesquise os dados.

    1. Por padrão, todas as colunas são retornadas. Para retornar colunas específicas, desative Retrieve All Columns e insira os nomes das colunas, separados por vírgulas.

      Nota

      Por padrão, o Tablestore retorna as colunas de chave primária da tabela de dados.

    2. Selecione um operador lógico: And, Or ou Not.

      Ao selecionar And, a consulta retorna dados que atendem a todas as condições especificadas. Ao selecionar Or, a consulta retorna dados que atendem a pelo menos uma das condições especificadas. Ao selecionar Not, a consulta retorna dados que não atendem às condições especificadas.

    3. Selecione um campo de índice do tipo Text e clique em Add.

    4. Defina o tipo de consulta para o campo de índice como Match Query (MatchQuery) e insira o valor a ser consultado.

    5. Por padrão, a ordenação está desativada. Para ordenar os resultados por um campo específico, ative Enable Sorting, adicione o campo de ordenação e configure a ordem de classificação.

    6. Por padrão, a agregação está desativada. Para executar agregação estatística em um campo específico, ative Enable Aggregation, adicione o campo para agregação e configure as definições de agregação.

  4. Clique em OK.

    Os resultados da consulta são exibidos na aba Index Management.

Usar a interface de linha de comando

Execute o comando search na interface de linha de comando para consultar dados usando um índice de pesquisa. Para mais informações, consulte Índice de pesquisa.

  1. Execute o comando search para consultar dados na tabela usando o índice de pesquisa search_index e retornar todas as colunas indexadas.

    search -n search_index --return_all_indexed
  2. Insira as condições de consulta conforme solicitado. Veja o exemplo a seguir:

    {
        "Offset": -1,
        "Limit": 10,
        "Collapse": null,
        "Sort": null,
        "GetTotalCount": true,
        "Token": null,
        "Query": {
            "Name": "MatchQuery",
            "Query": {
                "FieldName": "col_text",
                "Text": "this is",
                "MinimumShouldMatch": 1
            }
        }
    }

Usar um SDK

É possível executar uma consulta de correspondência usando o Java SDK, Go SDK, Python SDK, Node.js SDK, .NET SDK ou PHP SDK. Esta seção usa o SDK para Java como exemplo.

O exemplo a seguir consulta linhas cujo campo description contém o token tablestore ou durable e retorna até 10 linhas, o número total de linhas correspondidas e as pontuações de relevância.

String tableName = "example_table";
String indexName = "example_index";

MatchQuery matchQuery = new MatchQuery();
matchQuery.setFieldName("description");
matchQuery.setText("tablestore durable");

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(matchQuery);
searchQuery.setSort(new Sort(Collections.singletonList(new ScoreSort())));
searchQuery.setLimit(10);
searchQuery.setTrackTotalCount(SearchQuery.TRACK_TOTAL_COUNT);

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAll(true);
request.setColumnsToGet(columnsToGet);

SearchResponse response = client.search(request);
for (SearchHit hit : response.getSearchHits()) {
    System.out.println(hit.getRow());
    System.out.println(hit.getScore());
}

Faturamento

A consulta de dados por meio de um Search Index consome throughput de leitura. Para mais informações, consulte Medição e faturamento do Search Index.

Perguntas frequentes

Referências