Todos os produtos
Search
Central de documentação

Tablestore:Resumo e destaque

Última atualização: Oct 09, 2026

Para usar o recurso de resumo e destaque, crie um índice de pesquisa e ative o destaque para um campo Text. Em seguida, defina os parâmetros de destaque na sua consulta para retornar trechos que contenham as consultas de pesquisa correspondentes e destacar os termos encontrados.

Cenários

Use o recurso de resumo e destaque para extrair trechos próximos às consultas de pesquisa correspondentes e destacá-las. Esse recurso é útil em cenários de pesquisa de texto completo, como pesquisas na web, recuperação de registros de chat e pesquisas em documentos.

Visão geral do recurso

O recurso de resumo e destaque realça o texto nos resultados da pesquisa que corresponde ou é relevante para as suas consultas. Isso ajuda os usuários a encontrar rapidamente o conteúdo relevante e melhora a eficiência da recuperação de informações. Esse recurso também é compatível com estruturas de dados complexas que contêm tipos aninhados, como JSON, para localizar informações com precisão. Por padrão, o Tablestore usa as tags <em></em> para marcar as consultas de pesquisa correspondentes.

Para usar o recurso de resumo e destaque, aplique as seguintes configurações:

  1. Ao criar um índice de pesquisa, defina o parâmetro enableHighlighting como True para o campo Text. Para mais informações, consulte Create a search index.

    Importante

    Ative o recurso de resumo e destaque apenas para campos Text.

  2. Ao consultar dados, personalize o estilo de destaque e especifique parâmetros como o método de codificação para os fragmentos destacados, o número máximo de fragmentos a serem retornados, além das pre-tags e post-tags.

Para começar, crie um índice de pesquisa e ative o recurso de resumo e destaque para um campo Text. Se o valor do campo Text for query highlight test, use uma match phrase query para a palavra-chave highlight. Para isso, especifique os parâmetros de destaque e o fragmento destacado query <em>highlight</em> test será retornado.

Observações

  • Ao usar o recurso de resumo e destaque com MatchQuery ou MatchPhraseQuery, os termos correspondentes podem ser destacados por múltiplas pre-tags e post-tags.

  • Se o tipo de tokenizador para o campo Text for a tokenização semântica máxima, o recurso de resumo e destaque não será compatível ao usar MatchPhraseQuery para consultar dados.

  • A divisão de fragmentos pode separar um termo correspondente no texto. Nesse caso, o termo pode não ser destacado.

API

O recurso de resumo e destaque utiliza a API Search. Os tipos de consulta compatíveis são TermQuery, TermsQuery, MatchQuery, MatchPhraseQuery, PrefixQuery, WildcardQuery e NestedQuery.

Parâmetros

Ao usar o recurso de resumo e destaque, defina os parâmetros de destaque por meio do parâmetro Highlight. Para subcolunas de um tipo aninhado, defina os parâmetros de destaque usando o parâmetro InnerHits.

Parâmetros de Highlight

Nome

Tipo

Descrição

fieldHighlightParams (obrigatório)

Map<String, HighlightParameter>

Os nomes dos campos e as configurações de fragmento. A chave é o nome do campo cujos resultados de resumo e destaque você deseja retornar. O valor é o objeto HighlightParameter para o campo. O campo deve ter o resumo e o destaque ativados e deve ser usado em uma condição de consulta compatível.

highlightEncoder (opcional)

HighlightEncoder

O método de codificação para o texto original nos fragmentos destacados. Valores válidos:

  • PLAIN (padrão): não codifica o texto original.

  • HTML: aplica escape HTML ao texto original. Use este valor se exibir os resultados em uma página da web. Os caracteres <, >, ", ' e / sofrem escape como &lt;, &gt;, &quot;, &#x27; e &#x2F;, respectivamente.

fieldHighlightParams[].numberOfFragments (opcional)

Integer

O número máximo de fragmentos destacados a serem retornados para um campo. Para isso, defina este parâmetro como 1.

fieldHighlightParams[].fragmentSize (opcional)

Integer

O comprimento alvo de cada fragmento. O valor padrão é 100. O comprimento real do fragmento pode ser diferente desse valor.

fieldHighlightParams[].preTag (opcional)

String

A pre-tag para um termo correspondente. O valor padrão é <em>. Especifique uma tag personalizada, como <b>. Configure preTag e postTag em conjunto. Os caracteres compatíveis são < > " ' /, a-z, A-Z e 0-9.

fieldHighlightParams[].postTag (opcional)

String

A post-tag para um termo correspondente. O valor padrão é </em>. Especifique uma tag personalizada, como </b>. Configure preTag e postTag em conjunto. Os caracteres compatíveis são os mesmos de preTag.

fieldHighlightParams[].highlightFragmentOrder (opcional)

HighlightFragmentOrder

A ordem em que múltiplos fragmentos destacados são retornados. TEXT_SEQUENCE (padrão) classifica os fragmentos por suas posições no texto original. SCORE classifica os fragmentos pelas pontuações de relevância dos termos correspondentes.

Parâmetros de InnerHits

Parâmetro

Descrição

sort

A regra de classificação para as sublinhas aninhadas retornadas.

offset

A posição inicial a partir da qual retornar sublinhas quando uma coluna aninhada contém múltiplas sublinhas.

limit

O número de sublinhas a serem retornadas quando uma coluna aninhada contém múltiplas sublinhas. Valor padrão: 3.

highlight

A configuração do parâmetro de destaque para subcolunas aninhadas. Para mais informações sobre a configuração, consulte Highlight parameters.

Uso

Importante

Você só pode usar o recurso de resumo e destaque por meio de um sdk.

Antes de executar uma consulta com destaque, conclua as seguintes etapas de preparação:

  • Tenha uma conta Alibaba Cloud ou um usuário RAM com permissões para executar operações no Tablestore. Para conceder a um usuário RAM as permissões necessárias para operar no Tablestore, consulte Grant permissions to a RAM user using a RAM policy.

    Ao usar um sdk, caso não possua uma AccessKey válida, crie uma para a sua conta Alibaba Cloud ou usuário RAM. Para mais informações, consulte Create an AccessKey.

  • Crie uma tabela de dados. Para mais informações, consulte Data table operations.

  • Crie um índice de pesquisa para a tabela de dados e ative o destaque para o campo especificado. Para mais informações, consulte Create a search index.

  • Ao usar um sdk, inicialize o cliente do Tablestore. Para mais informações, consulte Initialize Tablestore Client.

Use o recurso de resumo e destaque com Java sdk, Go sdk, Python sdk e Node.js sdk. Os exemplos a seguir mostram como usar esse recurso com o sdk para Java.

Usando resumo e destaque de consulta para campos não aninhados

O exemplo a seguir usa uma match query para recuperar linhas nas quais o campo description contém o termo tablestore. O exemplo envolve os termos correspondentes nos fragmentos retornados com <b> e </b>. O campo description é um campo Text para o qual o resumo e o destaque estão ativados.

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

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

HighlightParameter highlightParameter = new HighlightParameter();
highlightParameter.setPreTag("<b>");
highlightParameter.setPostTag("</b>");

Highlight highlight = new Highlight();
highlight.addFieldHighlightParam("description", highlightParameter);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(matchQuery);
searchQuery.setHighlight(highlight);
searchQuery.setLimit(10);

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchResponse response = client.search(request);
for (SearchHit hit : response.getSearchHits()) {
    HighlightResultItem resultItem = hit.getHighlightResultItem();
    if (resultItem == null) {
        continue;
    }
    HighlightField field = resultItem.getHighlightFieldByName("description");
    if (field != null) {
        System.out.println(field.getFragments());
    }
}

Usando destaque ao consultar campos aninhados

O exemplo a seguir mostra como usar NestedQuery para consultar dados em que o valor do subcampo Level1_Col1_Nested no campo aninhado Col_Nested corresponde a `hangzhou shanghai`. A consulta de pesquisa é destacada nos resultados retornados.

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);

Suponha que o campo aninhado de múltiplos níveis Col_Nested inclua dois subcampos: Level1_Col1_Text (Text) e Level1_Col2_Nested (Nested). O campo aninhado Level1_Col2_Nested inclui o subcampo Level2_Col1_Text.

O exemplo a seguir mostra como adicionar uma BoolQuery a uma NestedQuery para usar os recursos de resumo e destaque tanto no subcampo Level1_Col1_Text do campo Col_Nested quanto no subcampo Level2_Col1_Text sob Level1_Col2_Nested.

public static void nestedQueryWithHighlighting(SyncClient client) { SearchRequest searchRequest = SearchRequest.newBuilder() .tableName("<TABLE_NAME>") .indexName("<SEARCH_INDEX_NAME>") .returnAllColumnsFromIndex(true) .searchQuery(SearchQuery.newBuilder() .limit(5) .query(QueryBuilders.nested() .path("Col_Nested") .scoreMode(ScoreMode.Min) .query(QueryBuilders.bool() .should(QueryBuilders.match("Col_Nested.Level1_Col1_Text", "hangzhou shanghai")) .should(QueryBuilders.nested() .path("Col_Nested.Level1_Col2_Nested") .scoreMode(ScoreMode.Min) .query(QueryBuilders.match("Col_Nested.Level1_Col2_Nested.Level2_Col1_Text", "hangzhou shanghai")) .innerHits(InnerHits.newBuilder() .highlight(Highlight.newBuilder() .addFieldHighlightParam("Col_Nested.Level1_Col2_Nested.Level2_Col1_Text", HighlightParameter.newBuilder().build()) .build()) .build()))) .innerHits(InnerHits.newBuilder() .sort(new Sort(Arrays.asList( new ScoreSort(), new DocSort() ))) .highlight(Highlight.newBuilder() .addFieldHighlightParam("Col_Nested.Level1_Col1_Text", HighlightParameter.newBuilder().build()) .build()) .build())) .build()) .build(); SearchResponse resp = client.search(searchRequest); // Print the highlighted results. printSearchHit(resp.getSearchHits(), ""); } /** Print the content of searchHit. @param searchHits The search hits. @param prefix The prefix to add when printing nested structures to show hierarchical information. / private static void printSearchHit(List<SearchHit> searchHits, String prefix) { for (SearchHit searchHit : searchHits) { if (searchHit.getScore() != null) { System.out.printf("%s Score: %s ", prefix, searchHit.getScore()); } if (searchHit.getOffset() != null) { System.out.printf("%s Offset: %s ", prefix, searchHit.getOffset()); } if (searchHit.getRow() != null) { System.out.printf("%s Row: %s ", prefix, searchHit.getRow().toString()); } // Print the highlighted fragments for each field. if (searchHit.getHighlightResultItem() != null) { System.out.printf("%s Highlight: ", prefix); StringBuilder strBuilder = new StringBuilder(); for (Map.Entry<String, HighlightField> entry : searchHit.getHighlightResultItem().getHighlightFields().entrySet()) { strBuilder.append(entry.getKey()).append(":").append("["); strBuilder.append(StringUtils.join(",", entry.getValue().getFragments())).append("] "); } System.out.printf("%s %s", prefix, strBuilder); } // Highlighted results for the nested type. for (SearchInnerHit searchInnerHit : searchHit.getSearchInnerHits().values()) { System.out.printf("%s Path: %s ", prefix, searchInnerHit.getPath()); System.out.printf("%s InnerHit: ", prefix); printSearchHit(searchInnerHit.getSubSearchHits(), prefix + " "); } System.out.println(); } }

Faturamento

O uso do recurso de resumo e destaque durante consultas de dados não afeta as regras de faturamento existentes.

Ao consultar dados usando um índice de pesquisa, a operação consome throughput de leitura. Para mais informações, consulte Search index metering and billing.

FAQ

Referências