Nested query - Tablestore SDK for Python - Tablestore - Centre de documentation Alibaba Cloud

Prérequis

Installez le SDK Tablestore pour Python et initialisez un client.

Description

Une requête imbriquée interroge les lignes enfants d'un champ Nested. Chaque ligne enfant conserve les relations entre ses champs. Vous ne pouvez pas interroger directement un champ enfant ; vous devez encapsuler la requête enfant dans un objet NestedQuery. Le paramètre path spécifie le chemin du champ Nested et les champs de la requête enfant doivent utiliser des chemins complets. La requête enfant peut être de n'importe quel type Query. Si plusieurs conditions doivent s'appliquer à la même ligne enfant, utilisez une BoolQuery contenant ces conditions comme requête enfant d'un seul NestedQuery. Si différentes lignes enfants peuvent satisfaire différentes conditions, créez un NestedQuery pour chaque condition et combinez-les avec une BoolQuery externe.

NestedQuery(path, query, score_mode=ScoreMode.NONE, inner_hits=None, weight=None)

L'exemple suivant interroge les lignes où la même ligne enfant du champ items Nested a un items.name égal à alice et un items.age inférieur à 40.

child_query = BoolQuery(
    must_queries=[
        TermQuery("items.name", "alice"),
        RangeQuery("items.age", range_to=40),
    ]
)
query = NestedQuery("items", child_query)
search_query = SearchQuery(
    query,
    limit=10,
    get_total_count=True,
)
response = client.search(
    "example_table",
    "example_index",
    search_query,
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.total_count)
for row in response.rows:
    print(row)

Paramètres

Requête de recherche

La méthode search accepte les paramètres suivants.

Nom	Type	Description
table_name (obligatoire)	`str`	Nom de la table de données.
index_name (obligatoire)	`str`	Nom de l'index de recherche.
search_query (obligatoire)	`SearchQuery`	Condition de requête et configurations courantes.
columns_to_get (facultatif)	`ColumnsToGet`	Configuration des colonnes à renvoyer. Par défaut, seules les colonnes de clé primaire sont renvoyées.
routing_keys (facultatif)	`list`	Liste des valeurs de clé primaire pour les champs de routage personnalisés. Inutile si le routage personnalisé n'est pas configuré.
timeout_s (facultatif)	`int`	Délai d'expiration de la requête en secondes. Par défaut, le délai d'expiration défini au niveau du client s'applique.

Configuration de la requête

L'objet search_query est de type SearchQuery et contient les paramètres suivants.

Nom	Type	Description
query (obligatoire)	`Query`	Condition de requête. Définissez ce paramètre sur `NestedQuery`.
sort (facultatif)	`Sort`	Ordre de tri des résultats. Pour plus d'informations, consultez Tri et pagination des résultats.
get_total_count (facultatif)	`bool`	Indique s'il faut renvoyer le nombre total de lignes correspondantes. Valeur par défaut : `False`. La valeur `True` augmente la charge de la requête.
next_token (facultatif)	`bytes`	Jeton de pagination. Définissez ce paramètre sur le `next_token` de la réponse précédente pour récupérer la page suivante. Pour plus d'informations, consultez Tri et pagination des résultats.
offset (facultatif)	`int`	Décalage de départ de la requête actuelle. Utilisez ce paramètre pour une pagination superficielle.
limit (facultatif)	`int`	Nombre maximal de lignes à renvoyer. La valeur `0` empêche le renvoi des données de ligne.
aggs (facultatif)	`list[Agg]`	Configurations d'agrégation. Pour plus d'informations, consultez Agrégation.
group_bys (facultatif)	`list[BaseGroupBy]`	Configurations de regroupement. Pour plus d'informations, consultez Agrégation.
collapse_field (facultatif)	`Collapse`	Configuration de réduction des résultats, qui supprime les doublons selon un champ spécifié. Pour plus d'informations, consultez Réduction des résultats de requête.

Condition de requête

L'objet search_query.query est de type NestedQuery et contient les paramètres suivants.

Nom	Type	Description
path (obligatoire)	`str`	Chemin du champ `Nested`. Pour un champ `Nested` multiniveau, spécifiez le chemin complet, par exemple `items.details`.
query (obligatoire)	`Query`	Condition de requête à exécuter sur les lignes enfants situées à `path`. Tout type de requête est autorisé. Les champs enfants doivent utiliser des chemins complets, tels que `items.name`.
score_mode (facultatif)	`ScoreMode`	Méthode de calcul du score de la ligne parente lorsque plusieurs lignes enfants correspondent. `NONE` (par défaut) ne calcule pas les scores de pertinence. `AVG`, `MAX`, `MIN` et `TOTAL` utilisent respectivement la moyenne, le maximum, le minimum et la somme des scores des lignes enfants.
inner_hits (facultatif)	`InnerHits`	Configurations de renvoi, de tri, de pagination et de mise en évidence pour les lignes enfants correspondantes. Par défaut, les détails des lignes enfants correspondantes ne sont pas renvoyés.
weight (facultatif)	`float`	Poids de pertinence de la condition de requête. La valeur doit être un nombre à virgule flottante positif. Valeur par défaut : `1.0`.

Lignes enfants correspondantes

L'objet search_query.query.inner_hits est de type InnerHits et contient les paramètres suivants.

Nom	Type	Description
sort (obligatoire)	`Sort`	Ordre de tri des lignes enfants correspondantes. Définissez ce paramètre sur `None` si aucun tri n'est requis.
offset (obligatoire)	`int`	Décalage de départ pour le renvoi des lignes enfants correspondantes. Transmettez `None` pour omettre cette valeur.
limit (obligatoire)	`int`	Nombre de lignes enfants correspondantes à renvoyer. Par défaut, le serveur renvoie trois lignes enfants si vous transmettez `None`.
highlight (obligatoire)	`Highlight`	Configuration de résumé et de mise en évidence pour les champs enfants. Définissez ce paramètre sur `None` si la mise en évidence n'est pas requise. Pour plus d'informations, consultez Résumé et mise en évidence.

Colonnes renvoyées

L'objet columns_to_get est de type ColumnsToGet et contient les paramètres suivants.

Nom	Type	Description
column_names (facultatif)	`list[str]`	Noms des colonnes d'attribut à renvoyer. Spécifiez ce paramètre uniquement lorsque `return_type` est défini sur `SPECIFIED`.
return_type (facultatif)	`ColumnReturnType`	Mode de renvoi des colonnes. `NONE` (par défaut) renvoie uniquement les colonnes de clé primaire ; `SPECIFIED` renvoie les colonnes d'attribut spécifiées dans `column_names` ; `ALL` renvoie toutes les colonnes d'attribut de la table ; `ALL_FROM_INDEX` renvoie toutes les colonnes d'attribut indexées.

Réponse

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

Champ	Type	Description
rows	`list[Row]`	Lignes renvoyées par la requête actuelle. Le nombre de lignes ne dépasse pas `limit`.
next_token	`bytes`	Jeton pour la page suivante. Si ce champ n'est pas vide, transmettez-le à la requête suivante pour poursuivre la lecture.
total_count	`int`	Nombre de lignes correspondantes. La valeur dépend de la configuration `get_total_count`.
is_all_succeed	`bool`	Indique si toutes les partitions d'index ont été interrogées. Si la valeur est `False`, des résultats partiels sont renvoyés et `total_count` peut être inférieur au nombre réel de lignes correspondantes.
agg_results	`list[AggResult]`	Résultats d'agrégation. Ce champ est vide si `aggs` n'est pas configuré.
group_by_results	`list[GroupByResult]`	Résultats de regroupement. Ce champ est vide si `group_bys` n'est pas configuré.
search_hits	`list[SearchHit]`	Hits de recherche, incluant des informations étendues telles que les scores de pertinence, les mises en évidence et les lignes enfants correspondantes.

Réponse compatible avec les tuples

À partir de la version 5.2.0 du SDK Tablestore pour Python, les API de recherche renvoient des objets de réponse au lieu de tuples. Les versions 5.1.0 et antérieures renvoient directement des tuples. À partir de la version 5.2.1, appelez SearchResponse.v1_response() pour obtenir un tuple compatible avec les versions antérieures. Pour le nouveau code, accédez directement aux attributs SearchResponse afin d'éviter les erreurs de déballage en cas d'extension des champs de réponse.

(
    rows,
    next_token,
    total_count,
    is_all_succeed,
    agg_results,
    group_by_results,
    search_hits,
) = response.v1_response()

Exemples

Renvoyer les lignes enfants correspondantes et les mises en évidence

L'exemple suivant interroge les lignes enfants imbriquées où items.name est égal à alice et renvoie les lignes enfants correspondantes ainsi que les fragments mis en évidence. Les résultats de mise en évidence sont disponibles à l'emplacement search_hits[].search_inner_hits[].search_hits[].highlight_result.

highlight = Highlight([HighlightParameter("items.name")])
inner_hits = InnerHits(
    sort=None,
    offset=0,
    limit=10,
    highlight=highlight,
)
query = NestedQuery(
    "items",
    TermQuery("items.name", "alice"),
    inner_hits=inner_hits,
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
)
for search_hit in response.search_hits:
    for inner_hit in search_hit.search_inner_hits:
        for child_hit in inner_hit.search_hits:
            print(child_hit.row)
            print(child_hit.highlight_result.highlight_fields)