Requête par termes - SDK Tablestore pour Python - Tablestore

Prérequis

Installez le SDK Tablestore pour Python et initialisez un client.

Description

Une requête par termes permet de faire correspondre plusieurs valeurs au sein d'un même champ. Une ligne correspond si au moins l'une des valeurs de la requête correspond exactement. Pour les champs non textuels tels que Keyword et Long, la valeur du champ doit correspondre exactement à l'une des valeurs de la requête. Ce fonctionnement s'apparente à la condition SQL IN. Pour un champ Text, une ligne correspond si l'un de ses jetons correspond exactement à une valeur de la requête. Les valeurs de requête ne sont pas tokenisées. La tokenisation peut varier selon la configuration de l'analyseur, les mises à jour des algorithmes et la langue utilisée. N'utilisez pas de requête par termes pour faire correspondre une chaîne complète dans un champ Text. Lors de l'appel à la méthode search, définissez le type de requête sur TermsQuery. Pour plus d'informations sur les types de champs, consultez la section Types de chaînes.

TermsQuery(field_name, column_values, weight=None)

L'exemple suivant interroge les lignes dont le champ category correspond exactement à books ou à games, et renvoie jusqu'à 10 lignes ainsi que le nombre total de lignes correspondantes.

query = TermsQuery("category", ["books", "games"])
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

Demande 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 de requête courantes.
columns_to_get (facultatif)	`ColumnsToGet`	Configuration des colonnes à renvoyer. Si ce paramètre n'est pas spécifié, seules les colonnes de clé primaire sont retournées.
routing_keys (facultatif)	`list`	Liste des valeurs de clé primaire pour les champs de routage personnalisé. Inutile de spécifier ce paramètre si le routage personnalisé n'est pas configuré.
timeout_s (facultatif)	`int`	Délai d'expiration de la requête en secondes. À défaut de spécification, le délai d'expiration défini au niveau du client s'applique.

Configuration de la requête

Le paramètre 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 `TermsQuery`.
sort (facultatif)	`Sort`	Ordre de tri des résultats de la requête. Pour plus d'informations, consultez la section Trier et paginer les résultats.
get_total_count (facultatif)	`bool`	Indique s'il faut renvoyer le nombre total de lignes correspondantes. Valeur par défaut : `False`. Définir ce paramètre sur `True` augmente la charge de la requête.
next_token (facultatif)	`bytes`	Jeton de pagination. Affectez à ce paramètre la valeur `next_token` issue de la réponse précédente pour récupérer la page suivante. Pour plus d'informations, consultez la section Trier et paginer les résultats.
offset (facultatif)	`int`	Décalage à partir duquel la requête actuelle commence. Utilisez ce paramètre pour une pagination superficielle.
limit (facultatif)	`int`	Nombre maximal de lignes à renvoyer. Si ce paramètre est défini sur `0`, aucune donnée de ligne n'est retournée.
aggs (facultatif)	`list[Agg]`	Configurations d'agrégation. Pour plus d'informations, consultez la section Agrégation.
group_bys (facultatif)	`list[BaseGroupBy]`	Configurations de regroupement. Pour plus d'informations, consultez la section Agrégation.
collapse_field (facultatif)	`Collapse`	Configuration de réduction des résultats, qui supprime les doublons en fonction d'un champ spécifié. Pour plus d'informations, consultez la section Réduire les résultats de la requête.
highlight (facultatif)	`Highlight`	Configuration de résumé et de mise en surbrillance pour les champs `Text`. Pour plus d'informations, consultez la section Résumé et mise en surbrillance.

Condition de requête

Le paramètre search_query.query est de type TermsQuery et contient les paramètres suivants.

Nom	Type	Description
field_name (obligatoire)	`str`	Nom du champ indexé à interroger.
column_values (obligatoire)	`list`	Liste des valeurs de requête. Vous pouvez spécifier jusqu'à 1 024 valeurs. Une ligne correspond si l'une des valeurs de la requête correspond exactement. Pour un champ `Text`, chaque valeur est traitée comme un jeton complet et n'est pas tokenisée.
weight (facultatif)	`float`	Poids de pertinence de la condition de requête. La valeur doit être un nombre à virgule flottante positif. Plus la valeur est élevée, plus elle contribue au score de pertinence BM25. Ce paramètre n'affecte ni la correspondance ni le nombre de lignes renvoyées. Il influe uniquement sur l'ordre lorsque les résultats sont triés par score de pertinence. Valeur par défaut : `1.0`.

Colonnes de retour

Le paramètre 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 retour des colonnes. `NONE` (valeur par défaut) renvoie uniquement les colonnes de clé primaire ; `SPECIFIED` renvoie les colonnes d'attribut listées dans `column_names` ; `ALL` renvoie toutes les colonnes d'attribut de la table ; et `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 la valeur de `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 de `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]`	Résultats de recherche, incluant des informations étendues telles que les scores de pertinence, les éléments mis en surbrillance 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 renvoyaient directement des tuples. Dans les versions 5.2.1 et ultérieures, vous pouvez appeler SearchResponse.v1_response() pour obtenir un tuple compatible avec les versions précédentes. Pour les nouveaux codes, accédez directement aux attributs de SearchResponse afin d'éviter les erreurs de déballage si des champs de réponse sont ajoutés à l'avenir.

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