Todos os produtos
Search
Central de documentação

Tablestore:Consulta de termos

Última atualização: Jul 03, 2026

A consulta de termos é semelhante à consulta de termo único, mas permite buscar por várias palavras-chave. O sistema retorna uma linha de dados quando o valor da coluna corresponde a pelo menos uma das palavras-chave especificadas. Esse tipo de consulta funciona como o operador IN em instruções SQL.

Operação de API

Para executar uma consulta de termos, chame a operação Search ou ParallelScan e defina o tipo de consulta como TermsQuery.

Parâmetros

Parâmetro

Descrição

query

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

fieldName

Nome do campo para correspondência.

terms

Termos de busca para correspondência. É possível especificar até 1.024 termos.

O sistema retorna uma linha de dados se o valor da coluna corresponder a pelo menos uma das palavras-chave.

getTotalCount

Define se o sistema deve retornar o número total de linhas que atendem às condições da consulta. O valor padrão é false, o que indica que a contagem total não será retornada.

Definir este parâmetro como true pode comprometer o desempenho da consulta.

weight

Peso atribuído ao campo consultado para calcular a pontuação de relevância de palavras-chave baseada em BM25. Utilizado em cenários de busca full-text. Quanto maior o peso definido para o campo, maior será sua pontuação de relevância BM25. Este parâmetro aceita um número de ponto flutuante positivo.

O peso não altera a quantidade de linhas retornadas, mas influencia diretamente a pontuação de relevância dos resultados da consulta.

tableName

Nome da tabela de dados.

indexName

Nome do índice de busca.

columnsToGet

Indica se o sistema deve retornar todas as colunas de cada linha correspondente. Configure os campos returnAll e columns para este parâmetro.

Por padrão, returnAll é false e nem todas as colunas são retornadas. Nesse caso, utilize o campo columns para definir quais colunas deseja obter. Se nenhuma coluna for especificada, apenas as colunas de chave primária serão retornadas.

Ao definir returnAll como true, todas as colunas serão incluídas na resposta.

Métodos

Você pode consultar termos usando o console do Tablestore, a CLI do Tablestore ou os SDKs do Tablestore. Antes de iniciar, certifique-se de cumprir os seguintes pré-requisitos:

Usar o console do Tablestore

  1. Acesse a aba Index Management.

    1. Faça login no console do Table Store.

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

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

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

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

  3. Na caixa de diálogo Search, especifique as condições da consulta.

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

      Nota

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

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

      Ao selecionar And, a consulta retorna dados que satisfazem todas as condições definidas. A opção Or traz resultados que atendem a pelo menos uma condição. Já o operador Not exclui os dados que correspondem às condições especificadas.

    3. Selecione um campo indexado e clique em Add.

    4. Defina o tipo de consulta do campo indexado como Terms query (TermsQuery), insira um valor e clique em Add.

      Para incluir múltiplos valores, repita o processo de inserir um Value e clicar em Add.

    5. A ordenação vem desativada por padrão. Caso precise ordenar os resultados por um campo específico, ative Enable Sorting, adicione o campo de ordenação e configure a direção da classificação.

    6. A agregação também é desativada por padrão. Para realizar agregações estatísticas em um campo, ative Enable Aggregation, adicione o campo alvo e ajuste as configurações de agregação.

  4. Clique em OK.

    Os resultados da consulta aparecerão na aba Index Management.

Usar a CLI do Tablestore

Execute o comando search na CLI do Tablestore para consultar dados por meio de índices de busca. Para mais informações, consulte Índice de busca.

  1. Execute o comando search utilizando o índice de busca search_index para consultar dados e retornar todas as colunas indexadas das linhas correspondentes.

    search -n search_index --return_all_indexed
  2. Insira as condições da consulta conforme solicitado pelo sistema:

    {
        "Offset": -1,
        "Limit": 10,
        "Collapse": null,
        "Sort": null,
        "GetTotalCount": true,
        "Token": null,
        "Query": {
            "Name": "TermsQuery",
            "Query": {
                "FieldName": "col_keyword",
                "Terms": ["hangzhou", "xi'an"]
            }
        }
    }

Usar os SDKs do Tablestore

Consulte termos utilizando os seguintes SDKs do Tablestore: Tablestore SDK for Java, Tablestore SDK for Go, Tablestore SDK for Python, Tablestore SDK for Node.js, Tablestore SDK for .NET e Tablestore SDK for PHP. O exemplo abaixo utiliza o Tablestore SDK for Java.

O código a seguir demonstra como buscar linhas onde o valor da coluna Col_Keyword seja "hangzhou" ou "xi'an":

/**
 * Search the table for rows in which the value of Col_Keyword is "hangzhou" or "xi'an". 
 * @param client
 */
private static void termQuery(SyncClient client) {
    SearchQuery searchQuery = new SearchQuery();
    TermsQuery termsQuery = new TermsQuery(); // Set the query type to TermsQuery. 
    termsQuery.setFieldName("Col_Keyword"); // Specify the name of the column that you want to match. 
    termsQuery.addTerm(ColumnValue.fromString("hangzhou")); // Specify the keyword that you want to match. 
    termsQuery.addTerm(ColumnValue.fromString("xi'an")); // Specify the keyword that you want to match. 
    searchQuery.setQuery(termsQuery);
    //searchQuery.setGetTotalCount(true); //Set the GetTotalCount parameter to true to return the total number of rows that meet the query conditions. 

    SearchRequest searchRequest = new SearchRequest("<TABLE_NAME>", "<SEARCH_INDEX_NAME>", searchQuery);
    // You can use the columnsToGet parameter to specify the columns that you want to return or specify that all columns are returned. If you do not specify this parameter, only the primary key columns are returned. 
    //SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
    //columnsToGet.setReturnAll(true); // Set the ReturnAll parameter to true to return all columns. 
    //columnsToGet.setColumns(Arrays.asList("ColName1","ColName2")); // Specify the columns that you want to return. 
    //searchRequest.setColumnsToGet(columnsToGet);

    SearchResponse resp = client.search(searchRequest);
    //System.out.println("TotalCount: " + resp.getTotalCount()); // Specify that the total number of rows that meet the query conditions instead of the number of returned rows is displayed. 
    System.out.println("Row: " + resp.getRows());
}

Faturamento

Consultar dados usando um Search Index consome throughput de leitura. Para mais informações, veja Medição e faturamento do Search Index.

Perguntas frequentes

Referências