Todos os produtos
Search

Este produto

    Tablestore:Nested query

    Central de documentação

    Tablestore:Nested query

    Última atualização: Jul 26, 2026

    Uma consulta aninhada com o Tablestore SDK for Java localiza dados em um campo Nested preservando os limites das linhas filhas e pode retornar as linhas filhas correspondentes.

    Pré-requisitos

    Instale o Tablestore SDK for Java e inicialize um cliente.

    Descrição do recurso

    Uma consulta aninhada pesquisa linhas filhas em um campo Nested. Cada linha filha dentro de um campo Nested preserva independentemente as relações entre seus campos. Não é possível consultar diretamente os subcampos de um campo Nested. Em vez disso, envolva a subconsulta em um objeto NestedQuery.

    O parâmetro NestedQuery.path especifica o caminho do campo aninhado a ser consultado. Os nomes dos campos na subconsulta devem usar caminhos completos. A subconsulta pode ser de qualquer tipo Query. Para consultar um campo aninhado multinível, defina path diretamente como o caminho completo do campo aninhado alvo ou aninhe objetos NestedQuery para consultar cada nível.

    A exigência de que múltiplas condições sejam atendidas pela mesma linha filha depende da combinação entre NestedQuery e BoolQuery:

    • Para exigir que a mesma linha filha atenda a várias condições, defina uma BoolQuery contendo as condições filhas como subconsulta de um único NestedQuery.

    • Para permitir que linhas filhas diferentes atendam às condições separadamente, crie um NestedQuery para cada condição e combine as consultas aninhadas em uma BoolQuery externa.

    Chame search para executar uma consulta aninhada. Na condição de consulta, especifique o caminho do campo aninhado, a subconsulta e o modo de pontuação.

    SearchResponse search(SearchRequest request)

    O exemplo a seguir consulta linhas filhas no campo aninhado items cujo campo items.keyword seja igual a tablestore. A consulta retorna até 10 linhas e o número total de correspondências.

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

TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.keyword");
termQuery.setTerm(ColumnValue.fromString("tablestore"));

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items");
nestedQuery.setQuery(termQuery);
nestedQuery.setScoreMode(ScoreMode.None);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(nestedQuery);
searchQuery.setLimit(10);
searchQuery.setTrackTotalCount(SearchQuery.TRACK_TOTAL_COUNT);

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchResponse response = client.search(request);
System.out.println(response.getTotalCount());
System.out.println(response.getRows());

    Parâmetros

    Solicitação de pesquisa

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

    Nome

    Tipo

    Descrição

    tableName (obrigatório)

    String

    Nome da tabela de dados.

    indexName (obrigatório)

    String

    Nome do índice de pesquisa.

    searchQuery (obrigatório)

    SearchQuery

    Condição de consulta e configurações gerais de pesquisa.

    columnsToGet (opcional)

    SearchRequest.ColumnsToGet

    Colunas a serem retornadas. Se este parâmetro não for configurado, apenas as colunas de chave primária serão retornadas.

    timeoutInMillisecond (opcional)

    int

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

    routingValues (opcional)

    List<PrimaryKey>

    Valores de chave primária correspondentes aos campos de roteamento personalizados. Deixe este 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

    Condição de consulta. Defina este parâmetro como um objeto NestedQuery para realizar uma consulta aninhada.

    offset (opcional)

    Integer

    Posição inicial da consulta.

    limit (opcional)

    Integer

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

    collapse (opcional)

    Collapse

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

    sort (opcional)

    Sort

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

    trackTotalCount (opcional)

    int

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

    filter (opcional)

    SearchFilter

    Filtro aplicado aos resultados de query.

    aggregationList (opcional)

    List<Aggregation>

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

    groupByList (opcional)

    List<GroupBy>

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

    token (opcional)

    byte[]

    Token de paginação. Defina este 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 ordenação.

    Condição de consulta aninhada

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

    Nome

    Tipo

    Descrição

    path (obrigatório)

    String

    Caminho do campo aninhado a ser consultado. Para um campo aninhado multinível, defina este parâmetro com o caminho completo do campo aninhado alvo, como items.details.

    query (obrigatório)

    Query

    Condição de consulta a ser executada nas linhas filhas sob path. A condição pode ser de qualquer tipo Query. Especifique um subcampo usando seu caminho completo, como items.keyword.

    scoreMode (obrigatório)

    ScoreMode

    Modo de pontuação da linha pai quando várias linhas filhas correspondem. None desativa a pontuação de relevância para linhas filhas. Avg, Max, Min e Total usam, respectivamente, a média, o máximo, o mínimo e a soma das pontuações das linhas filhas.

    innerHits (opcional)

    InnerHits

    Configurações para retornar, classificar, paginar e destacar linhas filhas correspondentes. Se você omitir este parâmetro, os detalhes sobre as linhas filhas correspondentes não serão retornados.

    weight (opcional)

    float

    Peso da consulta. O valor padrão é 1.0 e o valor deve ser um número de ponto flutuante positivo. Um valor maior aumenta as pontuações das linhas correspondentes, mas não altera quais linhas correspondem.

    Configurações de retorno de linhas filhas

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

    Nome

    Tipo

    Descrição

    sort (opcional)

    Sort

    Ordem de classificação das linhas filhas correspondentes. É possível usar ScoreSort e DocSort. FieldSort não é suportado.

    offset (opcional)

    Integer

    Posição inicial a partir da qual retornar linhas filhas correspondentes.

    limit (opcional)

    Integer

    Número máximo de linhas filhas correspondentes a retornar. O valor padrão é 3.

    highlight (opcional)

    Highlight

    Configurações de destaque para linhas filhas correspondentes. Para obter informações sobre campos e parâmetros que suportam destaque, consulte Summary and highlighting.

    Colunas retornadas

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

    Nome

    Tipo

    Descrição

    columns (opcional)

    List<String>

    Colunas de atributo a serem retornadas. Defina este parâmetro apenas se returnAll e returnAllFromIndex forem ambos false. Se você omitir este 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 pesquisa

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

    Nome

    Tipo

    Descrição

    totalCount

    long

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

    rows

    List<Row>

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

    searchHits

    List<SearchHit>

    Resultados da consulta. Chame getSearchHits() para obter o valor. Se innerHits estiver configurado, leia as linhas filhas correspondentes deste campo.

    nextToken

    byte[]

    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.

    Resultado da pesquisa

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

    Nome

    Tipo

    Descrição

    row

    Row

    Linha correspondente ou linha filha. Chame getRow() para obter o valor.

    score

    Double

    Pontuação de relevância. Chame getScore() para obter o valor.

    offset

    Integer

    Posição de uma linha filha aninhada no array original. Chame getOffset() para obter o valor. Este campo pode estar vazio em um resultado de linha pai.

    highlightResultItem

    HighlightResultItem

    Resultado do destaque. Chame getHighlightResultItem() para obter o valor.

    searchInnerHits

    Map<String, SearchInnerHit>

    Linhas filhas correspondentes agrupadas pelo caminho do campo aninhado. Chame getSearchInnerHits() para obter o mapa, ou chame getSearchInnerHitByPath(path) para obter o resultado de um caminho específico.

    Resultado aninhado

    response.searchHits[].searchInnerHits contém valores SearchInnerHit com os seguintes campos.

    Nome

    Tipo

    Descrição

    path

    String

    Caminho do campo aninhado. Chame getPath() para obter o valor.

    subSearchHits

    List<SearchHit>

    Linhas filhas correspondentes. Chame getSubSearchHits() para obter o valor. Em uma consulta aninhada multinível, searchInnerHits em um resultado de linha filha pode conter linhas correspondentes do próximo nível.

    Exemplos de cenários

    Consultar um campo aninhado multinível

    Para consultar um campo aninhado multinível, defina path com o caminho completo do campo aninhado alvo e especifique o caminho completo do subcampo na subconsulta. O exemplo a seguir consulta linhas nas quais items.details.name é igual a beta.

    TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.details.name");
termQuery.setTerm(ColumnValue.fromString("beta"));

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items.details");
nestedQuery.setQuery(termQuery);
nestedQuery.setScoreMode(ScoreMode.None);

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

    Exigir que a mesma linha filha atenda a várias condições

    Defina uma BoolQuery contendo múltiplas condições filhas como subconsulta de um único NestedQuery. O exemplo a seguir exige que a mesma linha filha em items tenha um valor items.keyword igual a tablestore e um campo items.number.

    TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.keyword");
termQuery.setTerm(ColumnValue.fromString("tablestore"));

ExistsQuery existsQuery = new ExistsQuery();
existsQuery.setFieldName("items.number");

BoolQuery childQuery = new BoolQuery();
childQuery.setMustQueries(Arrays.asList(termQuery, existsQuery));

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items");
nestedQuery.setQuery(childQuery);
nestedQuery.setScoreMode(ScoreMode.None);

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

    Permitir que linhas filhas diferentes atendam a várias condições

    Crie um NestedQuery para cada condição e combine as consultas aninhadas em uma BoolQuery externa. O exemplo a seguir permite que o valor items.keyword igual a tablestore e a existência de items.number sejam correspondidos por linhas filhas diferentes.

    TermQuery termQuery = new TermQuery();
termQuery.setFieldName("items.keyword");
termQuery.setTerm(ColumnValue.fromString("tablestore"));
NestedQuery termNestedQuery = new NestedQuery();
termNestedQuery.setPath("items");
termNestedQuery.setQuery(termQuery);
termNestedQuery.setScoreMode(ScoreMode.None);

ExistsQuery existsQuery = new ExistsQuery();
existsQuery.setFieldName("items.number");
NestedQuery existsNestedQuery = new NestedQuery();
existsNestedQuery.setPath("items");
existsNestedQuery.setQuery(existsQuery);
existsNestedQuery.setScoreMode(ScoreMode.None);

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustQueries(
        Arrays.asList(termNestedQuery, existsNestedQuery));

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

    Retornar e destacar linhas filhas correspondentes

    Use InnerHits para configurar o número, a ordem de classificação e as configurações de destaque das linhas filhas correspondentes. O exemplo a seguir consulta linhas filhas cujo campo items.description contenha hangzhou e retorna resultados destacados.

    MatchQuery matchQuery = new MatchQuery();
matchQuery.setFieldName("items.description");
matchQuery.setText("hangzhou");

HighlightParameter parameter = new HighlightParameter();
parameter.setPreTag("<em>");
parameter.setPostTag("</em>");
Highlight highlight = new Highlight();
highlight.addFieldHighlightParam("items.description", parameter);

InnerHits innerHits = new InnerHits();
innerHits.setLimit(3);
innerHits.setSort(new Sort(Arrays.asList(
        new ScoreSort(), new DocSort(SortOrder.ASC))));
innerHits.setHighlight(highlight);

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items");
nestedQuery.setQuery(matchQuery);
nestedQuery.setScoreMode(ScoreMode.None);
nestedQuery.setInnerHits(innerHits);

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

    Em uma consulta aninhada multinível, configure innerHits em cada nível de NestedQuery do qual linhas filhas correspondentes devam ser retornadas ou destacadas.