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

Prérequis

Installez le SDK Tablestore pour Python et initialisez un client.

Description

Une requête par terme fait correspondre un contenu strictement identique à la valeur de requête. Pour les champs non textuels tels que Keyword et Long, la valeur du champ doit correspondre exactement à la valeur de requête. Pour un champ Text, une ligne correspond si l'un des jetons correspond exactement à la valeur de requête. La valeur de requête n'est pas tokenisée. La tokenisation peut varier selon les configurations d'analyseur, les mises à jour d'algorithme et les langues. N'utilisez pas de requête par terme pour faire correspondre une chaîne complète dans un champ Text. Lorsque vous appelez la méthode search, définissez le type de requête sur TermQuery. Pour plus d'informations sur les types de champs, consultez la rubrique Types de chaînes.

TermQuery(field_name, column_value, weight=None)

L'exemple suivant interroge les lignes dont le champ category correspond exactement à book-python et renvoie jusqu'à 10 lignes ainsi que le nombre total de lignes correspondantes.

query = TermQuery("category", "book-python")
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. Si ce paramètre est omis, 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é. Ce paramètre est inutile si le routage personnalisé n'est pas configuré.

timeout_s (facultatif)

int

Délai d'expiration de la requête en secondes. À défaut, 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 accepte les paramètres suivants.

Nom

Type

Description

query (obligatoire)

Query

Condition de requête. Définissez ce paramètre sur TermQuery.

sort (facultatif)

Sort

Ordre de tri des résultats. Pour plus d'informations, consultez la rubrique 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. Définissez ce paramètre sur la valeur next_token de la réponse précédente pour récupérer la page suivante. Pour plus d'informations, consultez la rubrique Trier et paginer les résultats.

offset (facultatif)

int

Décalage de départ de la requête actuelle. Utilisez ce paramètre pour la 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 renvoyée.

aggs (facultatif)

list[Agg]

Configurations d'agrégation. Pour plus d'informations, consultez la rubrique Agrégation.

group_bys (facultatif)

list[BaseGroupBy]

Configurations de regroupement. Pour plus d'informations, consultez la rubrique 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 rubrique Réduire les résultats de requête.

highlight (facultatif)

Highlight

Configuration de résumé et de mise en surbrillance pour les champs Text. Pour plus d'informations, consultez la rubrique Résumé et mise en surbrillance.

Condition de requête

Le paramètre search_query.query est de type TermQuery et accepte les paramètres suivants.

Nom

Type

Description

field_name (obligatoire)

str

Nom du champ indexé à interroger.

column_value (obligatoire)

str / int / float / bool

Valeur de requête. Pour un champ Text, la valeur est utilisé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. Une valeur plus élevée contribue davantage 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 accepte 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 (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 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]

Occurrences de recherche, incluant des informations étendues telles que les scores de pertinence, les mises 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 renvoient directement des tuples. Dans la version 5.2.1 et ultérieure, vous pouvez appeler 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 si les champs de réponse sont étendus.

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