Utilisez le SDK Tablestore pour Python afin de contrôler l'ordre des résultats de l'index de recherche et de paginer ces résultats à l'aide d'un décalage (offset) ou d'un jeton next_token.
Prérequis
Installez le SDK Tablestore pour Python et initialisez un client.
Description
Les index de recherche prennent en charge le pré-tri de l'index et le tri au moment de la requête. Lors de la création d'un index de recherche, utilisez index_sort pour spécifier l'ordre par défaut. Si index_sort n'est pas spécifié, les lignes sont triées par clé primaire. Le pré-tri de l'index prend uniquement en charge PrimaryKeySort et FieldSort ; il n'est pas pris en charge pour un index contenant un champ Nested. Après la création, vous pouvez mettre à jour dynamiquement le schéma pour modifier le pré-tri de l'index. Au moment de la requête, utilisez SearchQuery.sort pour spécifier ScoreSort, PrimaryKeySort, FieldSort ou GeoDistanceSort, ou combinez plusieurs critères de tri dans l'ordre de la liste. À l'exception des clés primaires, les champs de tri doivent avoir le tri et l'agrégation activés lors de la création de l'index.
|
Méthode de pagination |
Description |
|
limit et offset |
Utilisez cette méthode lorsque les résultats ne dépassent pas 100 000 lignes et que vous devez accéder à une position spécifique. La somme |
|
next_token |
Privilégiez cette approche pour une pagination profonde ou pour lire séquentiellement tous les résultats. La profondeur de pagination n'est pas soumise à la limite de 100 000 lignes, mais les pages doivent être lues séquentiellement. |
L'exemple suivant renvoie les 10 premières lignes triées par score dans l'ordre décroissant, puis par clé primaire dans l'ordre croissant.
sort = Sort([
FieldSort("score", SortOrder.DESC),
PrimaryKeySort(SortOrder.ASC),
])
response = client.search(
"example_table",
"example_index",
SearchQuery(MatchAllQuery(), sort=sort, limit=10),
ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)Paramètres
Requête de recherche
La méthode search contient les paramètres suivants.
|
Nom |
Type |
Description |
|
table_name (obligatoire) |
|
Le nom de la table de données. |
|
index_name (obligatoire) |
|
Le nom de l'index de recherche. |
|
search_query (obligatoire) |
|
La condition de requête et les configurations courantes de la requête. |
|
columns_to_get (facultatif) |
|
La configuration des colonnes à renvoyer. Si ce paramètre n'est pas spécifié, seules les colonnes de clé primaire sont renvoyées. |
|
routing_keys (facultatif) |
|
Les 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) |
|
Le délai d'expiration de la requête en secondes. Si ce paramètre n'est pas spécifié, le délai d'expiration au niveau du client est utilisé. |
Configuration de la requête
search_query est de type SearchQuery et contient les paramètres de tri et de pagination suivants.
|
Nom |
Type |
Description |
|
query (obligatoire) |
|
La condition de requête. |
|
sort (facultatif) |
|
La configuration du tri au moment de la requête. Si omis, le pré-tri de l'index est utilisé. Ne le spécifiez pas lors de l'utilisation de |
|
offset (facultatif) |
|
Le décalage. Valeur par défaut : |
|
limit (facultatif) |
|
Le nombre maximal de lignes à renvoyer. Valeur par défaut : |
|
next_token (facultatif) |
|
Le jeton de pagination. Omettez-le dans la première requête et utilisez |
|
get_total_count (facultatif) |
|
Indique s'il faut renvoyer le nombre total de lignes correspondantes. Valeur par défaut : |
Configuration du tri
search_query.sort est de type Sort et contient le paramètre suivant.
|
Nom |
Type |
Description |
|
sorters (obligatoire) |
|
La liste des critères de tri. L'ordre de la liste détermine la priorité du tri multiniveau. Les types de critères de tri pris en charge sont |
Tri par score de pertinence
Si search_query.sort.sorters[] est de type ScoreSort, les lignes sont triées par score de pertinence. ScoreSort contient le paramètre suivant.
|
Nom |
Type |
Description |
|
sort_order (facultatif) |
|
L'ordre de tri. Valeur par défaut : |
Tri par clé primaire
Si search_query.sort.sorters[] est de type PrimaryKeySort, les lignes sont triées par clé primaire. PrimaryKeySort contient le paramètre suivant.
|
Nom |
Type |
Description |
|
sort_order (facultatif) |
|
L'ordre de tri. Valeur par défaut : |
Tri par champ
Si search_query.sort.sorters[] est de type FieldSort, les lignes sont triées par valeur de champ. FieldSort contient les paramètres suivants.
|
Nom |
Type |
Description |
|
field_name (obligatoire) |
|
Le nom du champ de tri. Le tri et l'agrégation doivent être activés pour le champ. |
|
sort_order (facultatif) |
|
L'ordre de tri. Valeur par défaut : |
|
sort_mode (facultatif) |
|
Le mode de sélection de valeur pour un champ multivalué : |
|
nested_filter (facultatif) |
|
La configuration du tri des champs enfants Nested, incluant le chemin Nested et une requête qui sélectionne les lignes enfants utilisées pour le tri. |
Filtre Nested
search_query.sort.sorters[].nested_filter est de type NestedFilter, peut être utilisé dans FieldSort ou GeoDistanceSort, et contient les paramètres suivants.
|
Nom |
Type |
Description |
|
path (obligatoire) |
|
Le chemin du champ Nested. |
|
query_filter (obligatoire) |
|
La condition de requête qui sélectionne les lignes enfants Nested utilisées pour le tri. Définissez ce paramètre sur |
Tri par distance géographique
Si search_query.sort.sorters[] est de type GeoDistanceSort, les lignes sont triées par la distance entre un point géographique et les points cibles. GeoDistanceSort contient les paramètres suivants.
|
Nom |
Type |
Description |
|
field_name (obligatoire) |
|
Le nom du champ de tri GeoPoint. |
|
points (obligatoire) |
|
Les points cibles au format |
|
sort_order (facultatif) |
|
|
|
sort_mode (facultatif) |
|
Le mode de sélection de valeur lorsque plusieurs distances existent : |
|
geo_distance_type (facultatif) |
|
La méthode de calcul de distance. |
|
nested_filter (facultatif) |
|
La configuration du tri des champs enfants Nested. |
Colonnes de retour
columns_to_get est de type ColumnsToGet et contient les paramètres suivants.
|
Nom |
Type |
Description |
|
column_names (facultatif) |
|
Les noms des colonnes d'attribut à renvoyer. Spécifiez ce paramètre uniquement lorsque |
|
return_type (facultatif) |
|
Le mode de colonne de retour. |
Réponse
La méthode search renvoie SearchResponse. Le tableau suivant décrit les champs principaux.
|
Champ |
Type |
Description |
|
rows |
|
Les lignes renvoyées par la requête. Le nombre ne dépasse pas |
|
next_token |
|
Le jeton pour la page suivante. Une valeur vide indique qu'aucune autre donnée n'est disponible. |
|
total_count |
|
Le 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 |
|
Les résultats d'agrégation de métriques. Ce champ est vide si |
|
group_by_results |
|
Les résultats de regroupement. Ce champ est vide si |
|
search_hits |
|
Les occurrences de recherche, incluant des informations étendues telles que les lignes, les scores de pertinence et les mises en évidence. |
Un next_token vide peut également indiquer que la requête n'a pas d'ordre de tri déterministe. total_count représente le nombre total de lignes correspondantes, et non le nombre de lignes de la page actuelle.
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é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
Trier par distance géographique
L'exemple suivant renvoie les résultats du plus proche au plus éloigné en fonction de la distance sphérique entre location et 30.25,120.16.
sort = Sort([
GeoDistanceSort(
"location",
["30.25,120.16"],
sort_order=SortOrder.ASC,
sort_mode=SortMode.MIN,
geo_distance_type=GeoDistanceType.ARC,
)
])
response = client.search(
"example_table",
"example_index",
SearchQuery(MatchAllQuery(), sort=sort, limit=10),
)
print(response.rows)Paginer à l'aide de next_token
Spécifiez l'ordre de tri dans la première requête. Dans les requêtes suivantes, transmettez uniquement next_token issu de la réponse précédente et la même condition de requête jusqu'à ce que le jeton soit vide.
query = MatchAllQuery()
response = client.search(
"example_table",
"example_index",
SearchQuery(query, sort=Sort([PrimaryKeySort()]), limit=100),
)
all_rows = list(response.rows)
while response.next_token:
response = client.search(
"example_table",
"example_index",
SearchQuery(query, next_token=response.next_token, limit=100),
)
all_rows.extend(response.rows)
print(len(all_rows))Lors de la pagination à l'aide de next_token, ne spécifiez pas offset et il est impossible de sauter directement des pages. Pour revenir en arrière, mettez en cache le jeton utilisé pour chaque page et interrogez à nouveau avec le jeton de la page cible. Un index de recherche contenant un champ Nested ne possède pas de pré-tri d'index. Spécifiez explicitement sort dans la première requête, sinon le serveur ne renvoie pas next_token.