Todos os produtos
Search

Este produto

    Tablestore:Boolean query

    Central de documentação

    Tablestore:Boolean query

    Última atualização: Aug 20, 2026

    Uma consulta booleana com o Tablestore SDK for Java combina várias condições de consulta usando a lógica AND, OR e NOT e retorna as linhas que atendem à condição combinada.

    Pré-requisitos

    Instale o Tablestore SDK for Java e inicialize um cliente.

    Descrição do recurso

    A consulta booleana usa BoolQuery para combinar uma ou mais subconsultas em uma condição complexa. Uma subconsulta pode ser de qualquer tipo Query, inclusive outro BoolQuery.

    O BoolQuery oferece suporte aos seguintes tipos de cláusula:

    • mustQueries: A linha deve corresponder a todas as subconsultas. As subconsultas correspondentes contribuem para a pontuação de relevância. Esse tipo de cláusula equivale a AND.

    • filterQueries: A linha deve corresponder a todas as subconsultas, mas as correspondências não contribuem para a pontuação de relevância. Essa cláusula também equivale a AND.

    • shouldQueries: A linha deve corresponder pelo menos ao número de subconsultas especificado por minShouldMatch. Corresponder a mais subconsultas resulta em uma pontuação de relevância maior. Esse tipo de cláusula equivale a OR.

    • mustNotQueries: A linha não deve corresponder a nenhuma subconsulta. Esse tipo de cláusula equivale a NOT e não contribui para a pontuação de relevância.

    Se minShouldMatch não estiver configurado e a consulta booleana contiver apenas shouldQueries e mustNotQueries, pelo menos uma subconsulta de shouldQueries deverá corresponder. Se a consulta booleana contiver mustQueries ou filterQueries no mesmo nível, as subconsultas de shouldQueries serão opcionais por padrão.

    Chame search para executar uma consulta booleana.

    SearchResponse search(SearchRequest request)

    O exemplo a seguir consulta linhas em que city é igual a hangzhou e category é igual a book. A consulta retorna até 10 linhas e o número total de correspondências.

    String tableName = "example_table";
String indexName = "example_index";
TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustQueries(Arrays.asList(cityQuery, categoryQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);
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);
System.out.println(response.getRows());

    Parâmetros

    Solicitação de busca

    request é um objeto SearchRequest que contém os seguintes parâmetros.

    Nome

    Tipo

    Descrição

    tableName (obrigatório)

    String

    O nome da tabela de dados.

    indexName (obrigatório)

    String

    O nome do índice de busca.

    searchQuery (obrigatório)

    SearchQuery

    A condição de consulta e as configurações gerais da consulta.

    columnsToGet (opcional)

    SearchRequest.ColumnsToGet

    As colunas a retornar. Se esse parâmetro não for configurado, apenas as colunas de chave primária serão retornadas.

    timeoutInMillisecond (opcional)

    int

    O tempo limite da consulta no nível da solicitação, em milissegundos. O valor padrão é -1, que não define um tempo limite separado para a consulta.

    routingValues (opcional)

    List<PrimaryKey>

    Os valores de chave primária correspondentes aos campos de roteamento personalizados. Deixe esse parâmetro indefinido se o roteamento personalizado não estiver configurado.

    Configurações de consulta

    request.searchQuery é um objeto SearchQuery que contém os seguintes parâmetros.

    Nome

    Tipo

    Descrição

    query (obrigatório)

    Query

    A condição de consulta. Defina esse parâmetro como um objeto BoolQuery para uma consulta booleana.

    offset (opcional)

    Integer

    A posição inicial da consulta.

    limit (opcional)

    Integer

    O número máximo de linhas a retornar. Defina esse parâmetro como 0 para não retornar nenhuma linha.

    highlight (opcional)

    Highlight

    As configurações de resumo e destaque quando uma subconsulta corresponde a um campo Text. Para obter detalhes de configuração, consulte Summary and highlighting.

    collapse (opcional)

    Collapse

    As configurações de colapso de campo, que removem duplicatas dos resultados com base em um campo especificado. Para obter detalhes de configuração, consulte Collapse query results.

    sort (opcional)

    Sort

    A ordem de classificação dos resultados. Para obter detalhes de configuração, consulte Sort and paginate results.

    trackTotalCount (opcional)

    int

    O número máximo esperado de linhas correspondentes a contar. O valor padrão é TRACK_TOTAL_COUNT_DISABLED, que desativa a contagem. Defina esse parâmetro como TRACK_TOTAL_COUNT para contar todas as linhas correspondentes. Um valor menor melhora o desempenho da consulta.

    filter (opcional)

    SearchFilter

    Um filtro aplicado aos resultados de query.

    aggregationList (opcional)

    List<Aggregation>

    As configurações de agregação. Para obter detalhes de configuração, consulte Aggregation.

    groupByList (opcional)

    List<GroupBy>

    As configurações de agrupamento. Para obter detalhes de configuração, consulte Aggregation.

    token (opcional)

    byte[]

    O token de paginação. Defina esse parâmetro com o valor nextToken da resposta anterior para continuar lendo linhas. Ao definir token, o SDK limpa sort porque o token já contém as condições de classificação.

    Condição de consulta booleana

    request.searchQuery.query é um objeto BoolQuery que contém os seguintes parâmetros.

    Nome

    Tipo

    Descrição

    mustQueries (opcional)

    List<Query>

    As subconsultas às quais uma linha deve corresponder integralmente. As subconsultas correspondentes contribuem para a pontuação de relevância. Esse tipo de cláusula equivale a AND.

    filterQueries (opcional)

    List<Query>

    As subconsultas às quais uma linha deve corresponder integralmente. As subconsultas correspondentes não contribuem para a pontuação de relevância. Esse tipo de cláusula equivale a AND.

    shouldQueries (opcional)

    List<Query>

    As subconsultas das quais um número mínimo especificado deve corresponder. Esse tipo de cláusula equivale a OR. Corresponder a mais subconsultas gera uma pontuação de relevância maior.

    mustNotQueries (opcional)

    List<Query>

    As subconsultas às quais nenhuma linha pode corresponder. Esse tipo de cláusula equivale a NOT e não contribui para a pontuação de relevância.

    minShouldMatch (opcional)

    String ou int

    O número mínimo de subconsultas shouldQueries que devem corresponder. Especifique um número inteiro, como 2, ou uma string de porcentagem, como "75%". Se esse parâmetro for omitido, o valor padrão será 0 quando mustQueries ou filterQueries existir no mesmo nível. Em outros casos que contenham shouldQueries, o valor padrão será 1.

    weight (opcional)

    Float

    O peso da consulta booleana. Se esse parâmetro for omitido, a consulta usará um peso de 1.0. Um valor maior aumenta a contribuição de mustQueries e shouldQueries para a pontuação final de relevância, sem alterar quais linhas correspondem.
    Nota

    setMinimumShouldMatch(Integer) está obsoleto. Use setMinShouldMatch(int) ou setMinShouldMatch(String).

    Colunas retornadas

    request.columnsToGet é um objeto SearchRequest.ColumnsToGet que contém os seguintes parâmetros.

    Nome

    Tipo

    Descrição

    columns (opcional)

    List<String>

    As colunas de atributo a retornar. Defina esse parâmetro apenas se returnAll e returnAllFromIndex forem ambos false. Se você omitir esse parâmetro, apenas as colunas de chave primária serão retornadas.

    returnAll (opcional)

    boolean

    Especifica se todas as colunas de atributo da tabela de dados devem ser retornadas. O valor padrão é false.

    returnAllFromIndex (opcional)

    boolean

    Especifica se todas as colunas de atributo indexadas devem ser retornadas. O valor padrão é false. Não defina returnAll e returnAllFromIndex como true simultaneamente.

    Valores de retorno

    Resposta da busca

    search retorna um objeto SearchResponse. A tabela a seguir descreve os campos principais.

    Nome

    Tipo

    Descrição

    totalCount

    long

    O número de linhas correspondentes. Chame getTotalCount() para obter o valor. O valor retornado depende da configuração de trackTotalCount.

    rows

    List<Row>

    As linhas retornadas por esta consulta. Chame getRows() para obter o valor. O número de linhas não excede limit.

    searchHits

    List<SearchHit>

    Os acertos da consulta. Chame getSearchHits() para obter o valor. Leia as pontuações de relevância e os resultados de resumo e destaque deste campo.

    nextToken

    byte[]

    O token da próxima página. Chame getNextToken() para obter o valor. Se o valor não for null, defina-o como token na próxima solicitação para continuar lendo linhas.

    isAllSuccess

    boolean

    Indica se todas as partições do índice foram consultadas com sucesso. Chame isAllSuccess() para obter o valor. Se o valor for false, a resposta conterá resultados parciais e totalCount poderá ser menor que o número real de linhas correspondentes.

    Acerto da busca

    response.searchHits[] é um objeto SearchHit que contém os seguintes campos principais.

    Nome

    Tipo

    Descrição

    row

    Row

    A linha correspondente. Chame getRow() para obter o valor.

    score

    Double

    A pontuação de relevância. Chame getScore() para obter o valor. Ao usar ScoreSort para classificar por pontuação de relevância, este campo contém a pontuação real.

    highlightResultItem

    HighlightResultItem

    O resultado de resumo e destaque. Chame getHighlightResultItem() para obter o valor.

    Exemplos de cenários

    Corresponder a qualquer condição

    Use shouldQueries para combinar condições e minShouldMatch para especificar o número mínimo de condições que devem corresponder. O exemplo a seguir consulta linhas em que city é igual a hangzhou ou category é igual a book.

    TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setShouldQueries(Arrays.asList(cityQuery, categoryQuery));
boolQuery.setMinShouldMatch(1);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);

    Excluir linhas que correspondem a uma condição

    Use mustNotQueries para excluir linhas que correspondam a qualquer condição especificada. O exemplo a seguir consulta linhas em que city não é igual a hangzhou.

    TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustNotQueries(Collections.singletonList(cityQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);

    Filtrar por múltiplas condições sem pontuação de relevância

    Use filterQueries para exigir que todas as subconsultas correspondam, sem permitir que as condições contribuam para a pontuação de relevância. O exemplo a seguir consulta linhas em que city é igual a hangzhou e category é igual a book.

    TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setFilterQueries(Arrays.asList(cityQuery, categoryQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);

    Aninhar combinações de condições

    Use um BoolQuery como subconsulta de outro BoolQuery para expressar lógica multinível. O exemplo a seguir implementa (city = "hangzhou" OR price < 150) OR (category = "book" AND (price = 300 OR price = 400)).

    TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

RangeQuery lowPriceQuery = new RangeQuery();
lowPriceQuery.setFieldName("price");
lowPriceQuery.lessThan(ColumnValue.fromLong(150));

BoolQuery firstGroup = new BoolQuery();
firstGroup.setShouldQueries(Arrays.asList(cityQuery, lowPriceQuery));

TermQuery price300Query = new TermQuery();
price300Query.setFieldName("price");
price300Query.setTerm(ColumnValue.fromLong(300));

TermQuery price400Query = new TermQuery();
price400Query.setFieldName("price");
price400Query.setTerm(ColumnValue.fromLong(400));

BoolQuery priceGroup = new BoolQuery();
priceGroup.setShouldQueries(Arrays.asList(price300Query, price400Query));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery secondGroup = new BoolQuery();
secondGroup.setMustQueries(Arrays.asList(categoryQuery, priceGroup));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setShouldQueries(Arrays.asList(firstGroup, secondGroup));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);