Utilisez le SDK Tablestore pour Python pour agréger des métriques et regrouper les résultats de l'index de recherche.
Prérequis
Installez le SDK Tablestore pour Python et initialisez un client.
La fonctionnalité d'agrégation nécessite la version 5.2.1 ou ultérieure du SDK. Nous vous recommandons d'utiliser la dernière version.
Description
L'agrégation calcule des métriques ou crée des groupes à partir des résultats des requêtes sur l'index de recherche. Ajoutez des objets d'agrégation de métriques à SearchQuery.aggs et des objets de regroupement à SearchQuery.group_bys. Chaque name d'une requête doit être unique et identifie le résultat correspondant dans la réponse. Pour ne récupérer que les résultats d'agrégation, définissez limit sur 0.
|
Fonctionnalité |
Description |
|
Min, Max, Sum, Avg |
Calcule les valeurs minimale, maximale, la somme et la moyenne. |
|
Count, DistinctCount |
Compte les lignes dont les valeurs de champ ne sont pas vides et les valeurs de champ distinctes. |
|
Percentiles |
Calcule un ou plusieurs centiles. |
|
TopRows |
Renvoie les premières lignes triées de chaque groupe sous forme de sous-agrégation. |
|
GroupByField, GroupByComposite |
Regroupe par valeur de champ unique ou par combinaison de champs. |
|
GroupByRange, GroupByGeoDistance, GroupByFilter |
Regroupe par plage numérique, distance géographique ou conditions de filtre. |
|
GroupByHistogram, GroupByDateHistogram, GroupByGeoGrid |
Crée des histogrammes numériques, des histogrammes de dates ou des groupes de grille GeoHash. |
Les champs d'index de recherche utilisés pour l'agrégation doivent avoir le tri et l'agrégation activés. Les types de champs pris en charge varient selon le type d'agrégation et de regroupement. Vous pouvez configurer jusqu'à cinq regroupements au même niveau. Le compte distinct, les centiles et le regroupement par champ utilisent un calcul approximatif. Un grand nombre d'agrégations ou des agrégations profondément imbriquées augmentent la complexité et la latence des requêtes.
L'exemple suivant calcule les valeurs minimale, maximale et moyenne de price et regroupe les lignes par category.
search_query = SearchQuery(
MatchAllQuery(),
limit=0,
aggs=[
Min("price", name="min_price"),
Max("price", name="max_price"),
Avg("price", name="avg_price"),
],
group_bys=[
GroupByField("category", name="by_category"),
],
)
response = client.search(
"example_table",
"example_index",
search_query,
)
for result in response.agg_results:
print(result.name, result.value)
for result in response.group_by_results:
print(result.name, result.items)Paramètres
Requête de recherche
La méthode search accepte les paramètres suivants.
|
Nom |
Type |
Description |
|
table_name (obligatoire) |
|
Nom de la table de données. |
|
index_name (obligatoire) |
|
Nom de l'index de recherche. |
|
search_query (obligatoire) |
|
Condition de requête et configurations courantes. |
|
columns_to_get (facultatif) |
|
Configuration des colonnes renvoyées. Si ce paramètre est omis, seules les colonnes de clé primaire sont renvoyées. |
|
routing_keys (facultatif) |
|
Valeurs de clé primaire des champs de routage personnalisés. Ce paramètre n'est pas requis si le routage personnalisé n'est pas configuré. |
|
timeout_s (facultatif) |
|
Délai d'expiration de la requête en secondes. Si ce paramètre est omis, le délai d'expiration du client s'applique. |
Configuration de la requête
search_query est de type SearchQuery et contient les paramètres suivants liés à l'agrégation.
|
Nom |
Type |
Description |
|
query (obligatoire) |
|
Condition de requête qui détermine la portée de l'agrégation. Utilisez |
|
aggs (facultatif) |
|
Liste des agrégations de métriques. Vous pouvez combiner des agrégations aux noms différents. |
|
group_bys (facultatif) |
|
Liste des regroupements. Vous pouvez combiner des regroupements aux noms différents. |
|
limit (facultatif) |
|
Nombre de lignes de requête à renvoyer. Définissez ce paramètre sur |
Agrégations de métriques
Ajoutez les objets suivants à search_query.aggs. field désigne le champ d'agrégation, name identifie le résultat et missing_value spécifie la valeur à utiliser lorsque le champ est manquant. Si missing_value n'est pas spécifié, les lignes sans ce champ sont ignorées.
Min, Max et Avg
|
Nom |
Type |
Description |
|
field (obligatoire) |
|
Champ d'agrégation. Types pris en charge : |
|
missing_value (facultatif) |
|
Valeur utilisée lorsque le champ est manquant. |
|
name (facultatif) |
|
Nom de l'agrégation. Valeurs par défaut : |
Sum
|
Nom |
Type |
Description |
|
field (obligatoire) |
|
Champ d'agrégation. Types pris en charge : |
|
missing_value (facultatif) |
|
Valeur utilisée dans la somme lorsque le champ est manquant. |
|
name (facultatif) |
|
Nom de l'agrégation. Valeur par défaut : |
Count
|
Nom |
Type |
Description |
|
field (obligatoire) |
|
Champ dont les lignes non vides sont comptées. Types pris en charge : |
|
name (facultatif) |
|
Nom de l'agrégation. Valeur par défaut : |
DistinctCount
|
Nom |
Type |
Description |
|
field (obligatoire) |
|
Champ dont les valeurs distinctes sont comptées. Types pris en charge : |
|
missing_value (facultatif) |
|
Valeur incluse dans le compte distinct lorsque le champ est manquant. |
|
name (facultatif) |
|
Nom de l'agrégation. Valeur par défaut : |
Percentiles
|
Nom |
Type |
Description |
|
field (obligatoire) |
|
Champ d'agrégation. Types pris en charge : |
|
percentiles_list (obligatoire) |
|
Centiles à calculer, par exemple |
|
missing_value (facultatif) |
|
Valeur utilisée lorsque le champ est manquant. |
|
name (facultatif) |
|
Nom de l'agrégation. Valeur par défaut : |
TopRows
|
Nom |
Type |
Description |
|
limit (obligatoire) |
|
Nombre maximal de lignes à renvoyer pour chaque groupe. |
|
sort (obligatoire) |
|
Ordre de tri des lignes dans chaque groupe. |
|
name (facultatif) |
|
Nom de l'agrégation. Valeur par défaut : |
DistinctCount est approximatif. Les résultats sont proches de la valeur exacte en dessous de 10 000 valeurs distinctes, avec une erreur d'environ 2 % pour 100 millions de valeurs. Percentiles est également approximatif ; les centiles extrêmes sont généralement plus précis que la médiane. Utilisez TopRows uniquement comme sous-agrégation d'un regroupement.
Regroupement
Ajoutez les objets suivants à search_query.group_bys. Utilisez sub_aggs et sub_group_bys pour effectuer des sous-agrégations de métriques et des sous-regroupements dans chaque groupe.
GroupByField
|
Nom |
Type |
Description |
|
field_name (obligatoire) |
|
Champ de regroupement. Types pris en charge : |
|
size (facultatif) |
|
Nombre de groupes à renvoyer. Valeur par défaut : |
|
group_by_sort (facultatif) |
|
Règles de tri des groupes. Par défaut, les groupes sont triés par nombre de lignes décroissant. |
|
sub_aggs (facultatif) |
|
Sous-agrégations de métriques. |
|
sub_group_bys (facultatif) |
|
Sous-regroupements. |
|
name (facultatif) |
|
Nom du regroupement. Valeur par défaut : |
GroupByComposite
|
Nom |
Type |
Description |
|
sources (obligatoire) |
|
Sources de regroupement multi-champs. Vous pouvez spécifier jusqu'à 32 sources de type |
|
size (facultatif) |
|
Nombre de groupes à renvoyer. Valeur par défaut : |
|
next_token (facultatif) |
|
Jeton pour la page suivante de groupes. Omettez-le lors de la première requête. |
|
suggested_size (facultatif) |
|
Limite souple pour les scénarios de calcul à haut débit. Ne le spécifiez pas conjointement avec |
|
sub_aggs (facultatif) |
|
Sous-agrégations de métriques. |
|
sub_group_bys (facultatif) |
|
Sous-regroupements. |
|
name (facultatif) |
|
Nom du regroupement. Valeur par défaut : |
GroupByRange
|
Nom |
Type |
Description |
|
field_name (obligatoire) |
|
Champ de regroupement. Types pris en charge : |
|
ranges (obligatoire) |
|
Plages fermées à gauche et ouvertes à droite, par exemple |
|
sub_aggs (facultatif) |
|
Sous-agrégations de métriques. |
|
sub_group_bys (facultatif) |
|
Sous-regroupements. |
|
name (facultatif) |
|
Nom du regroupement. Valeur par défaut : |
GroupByGeoDistance
|
Nom |
Type |
Description |
|
field_name (obligatoire) |
|
Champ de regroupement |
|
origin (obligatoire) |
|
Point central. Les paramètres du constructeur sont la latitude suivie de la longitude. |
|
ranges (obligatoire) |
|
Plages de distance en mètres. Chaque plage est fermée à gauche et ouverte à droite. |
|
sub_aggs (facultatif) |
|
Sous-agrégations de métriques. |
|
sub_group_bys (facultatif) |
|
Sous-regroupements. |
|
name (facultatif) |
|
Nom du regroupement. Valeur par défaut : |
GroupByFilter
|
Nom |
Type |
Description |
|
filters (obligatoire) |
|
Conditions de filtre. L'ordre des résultats correspond à l'ordre des conditions. |
|
sub_aggs (facultatif) |
|
Sous-agrégations de métriques. |
|
sub_group_bys (facultatif) |
|
Sous-regroupements. |
|
name (facultatif) |
|
Nom du regroupement. Valeur par défaut : |
GroupByHistogram
|
Nom |
Type |
Description |
|
field_name (obligatoire) |
|
Champ de regroupement. Types pris en charge : |
|
interval (obligatoire) |
|
Intervalle de l'histogramme numérique. |
|
field_range (obligatoire) |
|
Plage d'agrégation. |
|
missing_value (facultatif) |
|
Valeur utilisée dans l'histogramme lorsque le champ est manquant. |
|
min_doc_count (facultatif) |
|
Nombre minimal de lignes pour un compartiment. Les compartiments contenant moins de lignes ne sont pas renvoyés. |
|
group_by_sort (facultatif) |
|
Règles de tri des groupes. |
|
sub_aggs (facultatif) |
|
Sous-agrégations de métriques. |
|
sub_group_bys (facultatif) |
|
Sous-regroupements. |
|
name (facultatif) |
|
Nom du regroupement. Valeur par défaut : |
GroupByDateHistogram
|
Nom |
Type |
Description |
|
field_name (obligatoire) |
|
Champ de regroupement |
|
interval (obligatoire) |
|
Intervalle de date ou d'heure, composé d'une valeur et de |
|
field_range (obligatoire) |
|
Plage d'agrégation. Le serveur requiert ce paramètre bien que le constructeur Python permette de l'omettre. |
|
missing (facultatif) |
|
Valeur de date utilisée dans l'histogramme lorsque le champ est manquant. |
|
min_doc_count (facultatif) |
|
Nombre minimal de lignes pour un compartiment. Les compartiments contenant moins de lignes ne sont pas renvoyés. |
|
time_zone (facultatif) |
|
Fuseau horaire au format |
|
group_by_sort (facultatif) |
|
Règles de tri des groupes. |
|
offset (facultatif) |
|
Décalage des limites de compartiment par rapport à l'origine par défaut. |
|
sub_aggs (facultatif) |
|
Sous-agrégations de métriques. |
|
sub_group_bys (facultatif) |
|
Sous-regroupements. |
|
name (facultatif) |
|
Nom du regroupement. Valeur par défaut : |
GroupByGeoGrid
|
Nom |
Type |
Description |
|
field_name (obligatoire) |
|
Champ de regroupement |
|
precision (obligatoire) |
|
Précision de la grille GeoHash. Un numéro d'énumération plus élevé représente une grille plus petite. |
|
size (facultatif) |
|
Nombre de groupes de grille à renvoyer. |
|
sub_aggs (facultatif) |
|
Sous-agrégations de métriques. |
|
sub_group_bys (facultatif) |
|
Sous-regroupements. |
|
name (facultatif) |
|
Nom du regroupement. Valeur par défaut : |
GroupByComposite nécessite le SDK Tablestore pour Python 6.4.4 ou une version ultérieure. S'il existe de nombreux groupes, spécifiez size et paginez en utilisant next_token de chaque résultat jusqu'à ce que le jeton soit vide.
Colonnes renvoyées
columns_to_get est de type ColumnsToGet et contient les paramètres suivants.
|
Nom |
Type |
Description |
|
column_names (facultatif) |
|
Noms des colonnes d'attributs à renvoyer. Spécifiez ce paramètre uniquement lorsque |
|
return_type (facultatif) |
|
Mode de renvoi des colonnes. |
Réponse
La méthode search renvoie un objet SearchResponse. Le tableau suivant décrit les champs principaux.
|
Champ |
Type |
Description |
|
rows |
|
Lignes renvoyées par la requête. Le nombre ne dépasse pas |
|
next_token |
|
Jeton pour la page suivante. Une valeur vide indique qu'aucune autre donnée n'est disponible. |
|
total_count |
|
Nombre de lignes correspondantes. La valeur dépend de |
|
is_all_succeed |
|
Indique si toutes les partitions d'index ont été interrogées. Si la valeur est |
|
agg_results |
|
Résultats d'agrégation de métriques. Ce champ est vide si |
|
group_by_results |
|
Résultats de regroupement. Ce champ est vide si |
|
search_hits |
|
Résultats de recherche, y compris des informations étendues telles que les lignes, les scores de pertinence et les mises en évidence. |
Chaque élément de agg_results utilise name et value pour identifier une agrégation et sa valeur. Chaque élément de group_by_results utilise name et items pour renvoyer les clés de groupe, le nombre de lignes, les sous-agrégations et les sous-regroupements. Un résultat GroupByComposite contient également source_group_by_names et next_token pour les lectures continues. Les keys de chaque groupe constituent une liste de chaînes alignée avec sources ; une valeur de champ manquante est représentée par None.
Réponse compatible avec les tuples
À partir du SDK Tablestore pour Python 5.2.0, 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érieures, 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()Exemples
Paginer un regroupement multi-champs
L'exemple suivant regroupe par category et price et renvoie deux groupes par page.
sources = [
GroupByField("category", name="category_source"),
GroupByField("price", name="price_source"),
]
next_token = None
all_items = []
while True:
group_by = GroupByComposite(
sources,
size=2,
next_token=next_token,
name="by_category_and_price",
)
response = client.search(
"example_table",
"example_index",
SearchQuery(MatchAllQuery(), limit=0, group_bys=[group_by]),
)
result = response.group_by_results[0]
all_items.extend(result.items)
next_token = result.next_token
if not next_token:
break
for item in all_items:
print(item.keys, item.row_count)Créer un histogramme de dates et une grille géographique
L'exemple suivant crée un histogramme de dates quotidien et regroupe les emplacements dans des grilles GeoHash d'environ 39 km par 19 km.
group_bys = [
GroupByDateHistogram(
"event_date",
DateTimeValue(1, DateTimeUnit.DAY),
field_range=FieldRange("2026-08-01", "2026-08-04"),
name="by_day",
),
GroupByGeoGrid(
"location",
GeoHashPrecision.GHP_39KM_19KM_4,
name="by_geo_grid",
),
]
response = client.search(
"example_table",
"example_index",
SearchQuery(MatchAllQuery(), limit=0, group_bys=group_bys),
)
for result in response.group_by_results:
print(result.name, result.items)