Tous les produits
Search

Ce produit

    Tablestore:Nested query

    Centre de documentation

    Tablestore:Nested query

    Dernière mise à jour :Aug 08, 2026

    Une requête imbriquée avec le SDK Tablestore pour Java interroge les données d'un champ Nested tout en préservant les limites des lignes enfants et peut renvoyer ces dernières.

    Prérequis

    Installez le SDK Tablestore pour Java et initialisez un client.

    Description de la fonctionnalité

    Une requête imbriquée interroge les lignes enfants d'un champ Nested. Chaque ligne enfant d'un champ Nested conserve indépendamment les relations entre ses champs. Il est impossible d'interroger directement les sous-champs d'un champ Nested ; vous devez encapsuler la sous-requête dans un objet NestedQuery.

    La propriété NestedQuery.path spécifie le chemin du champ imbriqué à interroger. Les noms de champs dans la sous-requête doivent utiliser des chemins complets. La sous-requête peut être de n'importe quel type Query. Pour interroger un champ imbriqué à plusieurs niveaux, définissez directement le paramètre path sur le chemin complet du champ cible ou imbriquez des objets NestedQuery pour interroger chaque niveau.

    Le fait que plusieurs conditions doivent être satisfaites par la même ligne enfant dépend de la combinaison des objets NestedQuery et BoolQuery :

    • Pour exiger que la même ligne enfant satisfasse plusieurs conditions, utilisez un objet BoolQuery contenant les conditions enfants comme sous-requête d'un unique objet NestedQuery.

    • Pour permettre à différentes lignes enfants de satisfaire séparément les conditions, créez un objet NestedQuery par condition et combinez ces requêtes imbriquées dans un objet BoolQuery externe.

    Appelez la méthode search pour exécuter une requête imbriquée. Dans la condition de requête, spécifiez le chemin du champ imbriqué, la sous-requête et le mode de calcul du score.

    SearchResponse search(SearchRequest request)

    L'exemple suivant interroge les lignes enfants du champ imbriqué items dont le champ items.keyword est égal à tablestore. La requête renvoie au maximum 10 lignes ainsi que le nombre total de correspondances.

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

    Paramètres

    Requête de recherche

    Le paramètre request est un objet SearchRequest qui contient les paramètres suivants.

    Nom

    Type

    Description

    tableName (obligatoire)

    String

    Nom de la table de données.

    indexName (obligatoire)

    String

    Nom de l'index de recherche.

    searchQuery (obligatoire)

    SearchQuery

    Condition de requête et paramètres généraux de la requête.

    columnsToGet (facultatif)

    SearchRequest.ColumnsToGet

    Colonnes à renvoyer. Si ce paramètre n'est pas configuré, seules les colonnes de clé primaire sont renvoyées.

    timeoutInMillisecond (facultatif)

    int

    Délai d'expiration de la requête au niveau de la demande, en millisecondes. La valeur par défaut est -1, ce qui signifie qu'aucun délai d'expiration spécifique n'est configuré pour la requête.

    routingValues (facultatif)

    List<PrimaryKey>

    Valeurs de clé primaire correspondant aux champs de routage personnalisés. Laissez ce paramètre non défini si aucun routage personnalisé n'est configuré.

    Paramètres de la requête

    L'objet request.searchQuery est un objet SearchQuery qui contient les paramètres suivants.

    Nom

    Type

    Description

    query (obligatoire)

    Query

    Condition de requête. Définissez ce paramètre sur un objet NestedQuery pour effectuer une requête imbriquée.

    offset (facultatif)

    Integer

    Position de départ de la requête.

    limit (facultatif)

    Integer

    Nombre maximal de lignes à renvoyer. Définissez ce paramètre sur 0 pour ne renvoyer aucune ligne.

    collapse (facultatif)

    Collapse

    Paramètres de regroupement (collapse), qui dédupliquent les résultats selon un champ spécifié. Pour plus de détails sur la configuration, consultez Regrouper les résultats de requête.

    sort (facultatif)

    Sort

    Ordre de tri des résultats. Pour plus de détails sur la configuration, consultez Trier et paginer les résultats.

    trackTotalCount (facultatif)

    int

    Nombre maximal attendu de lignes correspondantes à comptabiliser. La valeur par défaut est TRACK_TOTAL_COUNT_DISABLED, ce qui désactive le comptage. Définissez ce paramètre sur TRACK_TOTAL_COUNT pour compter toutes les lignes correspondantes. Une valeur plus faible améliore les performances de la requête.

    filter (facultatif)

    SearchFilter

    Filtre appliqué aux résultats de la requête query.

    aggregationList (facultatif)

    List<Aggregation>

    Paramètres d'agrégation. Pour plus de détails sur la configuration, consultez Agrégation.

    groupByList (facultatif)

    List<GroupBy>

    Paramètres de regroupement. Pour plus de détails sur la configuration, consultez Agrégation.

    token (facultatif)

    byte[]

    Jeton de pagination. Définissez ce paramètre sur la valeur nextToken de la réponse précédente pour continuer à lire les lignes. Lorsque vous définissez le paramètre token, le SDK efface le paramètre sort car le jeton contient déjà les conditions de tri.

    Condition de requête imbriquée

    L'objet request.searchQuery.query est un objet NestedQuery qui contient les paramètres suivants.

    Nom

    Type

    Description

    path (obligatoire)

    String

    Chemin du champ imbriqué à interroger. Pour un champ imbriqué à plusieurs niveaux, définissez ce paramètre sur le chemin complet du champ cible, par exemple items.details.

    query (obligatoire)

    Query

    Condition de requête à exécuter sur les lignes enfants situées sous le chemin path. La condition peut être de n'importe quel type Query. Spécifiez un sous-champ en utilisant son chemin complet, par exemple items.keyword.

    scoreMode (obligatoire)

    ScoreMode

    Mode de calcul du score pour la ligne parent lorsque plusieurs lignes enfants correspondent. La valeur None désactive le calcul de la pertinence pour les lignes enfants. Les valeurs Avg, Max, Min et Total utilisent respectivement la moyenne, le maximum, le minimum et la somme des scores des lignes enfants.

    innerHits (facultatif)

    InnerHits

    Paramètres permettant de renvoyer, trier, paginer et mettre en surbrillance les lignes enfants correspondantes. Si vous omettez ce paramètre, les détails concernant les lignes enfants correspondantes ne sont pas renvoyés.

    weight (facultatif)

    float

    Poids de la requête. La valeur par défaut est 1.0 et la valeur doit être un nombre flottant positif. Une valeur plus élevée augmente les scores des lignes correspondantes sans modifier les lignes qui correspondent.

    Paramètres de renvoi des lignes enfants

    L'objet request.searchQuery.query.innerHits est un objet InnerHits qui contient les paramètres suivants.

    Nom

    Type

    Description

    sort (facultatif)

    Sort

    Ordre de tri des lignes enfants correspondantes. Vous pouvez utiliser ScoreSort et DocSort. FieldSort n'est pas pris en charge.

    offset (facultatif)

    Integer

    Position de départ à partir de laquelle renvoyer les lignes enfants correspondantes.

    limit (facultatif)

    Integer

    Nombre maximal de lignes enfants correspondantes à renvoyer. La valeur par défaut est 3.

    highlight (facultatif)

    Highlight

    Paramètres de mise en surbrillance pour les lignes enfants correspondantes. Pour obtenir des informations sur les champs et paramètres prenant en charge la mise en surbrillance, consultez Résumé et mise en surbrillance.

    Colonnes renvoyées

    L'objet request.columnsToGet est un objet SearchRequest.ColumnsToGet qui contient les paramètres suivants.

    Nom

    Type

    Description

    columns (facultatif)

    List<String>

    Colonnes d'attribut à renvoyer. Définissez ce paramètre uniquement si returnAll et returnAllFromIndex ont tous deux la valeur false. Si vous omettez ce paramètre, seules les colonnes de clé primaire sont renvoyées.

    returnAll (facultatif)

    boolean

    Indique s'il faut renvoyer toutes les colonnes d'attribut de la table de données. La valeur par défaut est false.

    returnAllFromIndex (facultatif)

    boolean

    Indique s'il faut renvoyer toutes les colonnes d'attribut indexées. La valeur par défaut est false. Ne définissez pas simultanément returnAll et returnAllFromIndex sur true.

    Valeurs de retour

    Réponse de recherche

    La méthode search renvoie un objet SearchResponse. Le tableau suivant décrit les champs principaux.

    Nom

    Type

    Description

    totalCount

    long

    Nombre de lignes correspondantes. Appelez la méthode getTotalCount() pour obtenir la valeur. La valeur renvoyée dépend du paramètre trackTotalCount.

    rows

    List<Row>

    Lignes renvoyées par cette requête. Appelez la méthode getRows() pour obtenir la valeur. Le nombre de lignes ne dépasse pas la valeur du paramètre limit.

    searchHits

    List<SearchHit>

    Résultats de la requête (hits). Appelez la méthode getSearchHits() pour obtenir la valeur. Si le paramètre innerHits est configuré, lisez les lignes enfants correspondantes à partir de ce champ.

    nextToken

    byte[]

    Jeton pour la page suivante. Appelez la méthode getNextToken() pour obtenir la valeur. Si la valeur n'est pas null, définissez-la comme paramètre token dans la requête suivante pour continuer à lire les lignes.

    isAllSuccess

    boolean

    Indique si toutes les partitions d'index ont été interrogées avec succès. Appelez la méthode isAllSuccess() pour obtenir la valeur. Si la valeur est false, la réponse contient des résultats partiels et la valeur totalCount peut être inférieure au nombre réel de lignes correspondantes.

    Résultat de recherche (SearchHit)

    L'élément response.searchHits[] est un objet SearchHit qui contient les champs principaux suivants.

    Nom

    Type

    Description

    row

    Row

    Ligne correspondante ou ligne enfant correspondante. Appelez la méthode getRow() pour obtenir la valeur.

    score

    Double

    Score de pertinence. Appelez la méthode getScore() pour obtenir la valeur.

    offset

    Integer

    Position d'une ligne enfant imbriquée dans le tableau d'origine. Appelez la méthode getOffset() pour obtenir la valeur. Ce champ peut être vide dans un résultat correspondant à une ligne parent.

    highlightResultItem

    HighlightResultItem

    Résultat de la mise en surbrillance. Appelez la méthode getHighlightResultItem() pour obtenir la valeur.

    searchInnerHits

    Map<String, SearchInnerHit>

    Lignes enfants correspondantes regroupées par chemin de champ imbriqué. Appelez la méthode getSearchInnerHits() pour obtenir la map, ou appelez la méthode getSearchInnerHitByPath(path) pour obtenir le résultat pour un chemin spécifique.

    Résultat imbriqué (NestedHit)

    L'objet response.searchHits[].searchInnerHits contient des valeurs SearchInnerHit avec les champs suivants.

    Nom

    Type

    Description

    path

    String

    Chemin du champ imbriqué. Appelez la méthode getPath() pour obtenir la valeur.

    subSearchHits

    List<SearchHit>

    Lignes enfants correspondantes. Appelez la méthode getSubSearchHits() pour obtenir la valeur. Dans une requête imbriquée à plusieurs niveaux, le champ searchInnerHits d'un résultat correspondant à une ligne enfant peut contenir les lignes correspondantes du niveau suivant.

    Exemples de scénarios

    Interroger un champ imbriqué à plusieurs niveaux

    Pour interroger un champ imbriqué à plusieurs niveaux, définissez le paramètre path sur le chemin complet du champ cible et spécifiez le chemin complet du sous-champ dans la sous-requête. L'exemple suivant interroge les lignes dont le champ items.details.name est égal à 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);

    Exiger que la même ligne enfant satisfasse plusieurs conditions

    Utilisez un objet BoolQuery contenant plusieurs conditions enfants comme sous-requête d'un unique objet NestedQuery. L'exemple suivant exige que la même ligne enfant du champ items ait une valeur items.keyword égale à tablestore et possède un champ 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);

    Permettre à différentes lignes enfants de satisfaire plusieurs conditions

    Créez un objet NestedQuery pour chaque condition et combinez les requêtes imbriquées dans un objet BoolQuery externe. L'exemple suivant permet à la valeur items.keyword égale à tablestore et à l'existence du champ items.number d'être satisfaites par différentes lignes enfants.

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

    Renvoyer et mettre en surbrillance les lignes enfants correspondantes

    Utilisez l'objet InnerHits pour configurer le nombre, l'ordre de tri et les paramètres de mise en surbrillance des lignes enfants correspondantes. L'exemple suivant interroge les lignes enfants dont le champ items.description contient hangzhou et renvoie les résultats avec mise en surbrillance.

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

    Dans une requête imbriquée à plusieurs niveaux, configurez le paramètre innerHits dans chaque niveau NestedQuery à partir duquel les lignes enfants correspondantes doivent être renvoyées ou mises en surbrillance.