Terms query - Tablestore SDK for Java - Tablestore - Centre de documentation Alibaba Cloud

Prérequis

Installez le SDK Tablestore pour Java et initialisez le client.

Description de la fonctionnalité

Une requête par termes compare un champ spécifié à plusieurs termes de recherche et renvoie une ligne si au moins un terme satisfait la condition de correspondance exacte. Pour les champs non textuels, tels que les champs Keyword et Long, la valeur entière du champ doit être strictement égale à l'un des termes de recherche. Cette combinaison OU s'apparente à la condition SQL IN. Pour un champ Text (voir Types de chaînes), la ligne correspond si n'importe quel jeton généré par l'analyseur correspond exactement à l'un des termes de recherche. Les termes de recherche eux-mêmes ne sont pas tokenisés.

Remarque

Les jetons générés pour un champ Text peuvent varier en fonction de la configuration de l'analyseur, des mises à jour d'algorithmes et de l'évolution linguistique. Évitez d'utiliser une requête par termes pour faire correspondre la chaîne originale complète d'un champ Text. Privilégiez plutôt l'utilisation d'une colonne virtuelle afin de mapper le champ source vers le type Keyword, puis effectuez la requête sur cette colonne virtuelle.

Pour appeler search, définissez le type de requête sur TermsQuery et utilisez SearchQuery pour configurer le nombre de lignes renvoyées, le suivi du nombre total ainsi que d'autres comportements courants de requête.

SearchResponse search(SearchRequest request)

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

String tableName = "example_table";
String indexName = "example_index";

TermsQuery termsQuery = new TermsQuery();
termsQuery.setFieldName("category");
termsQuery.addTerm(ColumnValue.fromString("books"));
termsQuery.addTerm(ColumnValue.fromString("games"));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(termsQuery);
searchQuery.setLimit(10);
searchQuery.setTrackTotalCount(SearchQuery.TRACK_TOTAL_COUNT);

SearchRequest request = new SearchRequest(tableName, indexName, searchQuery);
SearchRequest.ColumnsToGet columnsToGet = new SearchRequest.ColumnsToGet();
columnsToGet.setReturnAll(true);
request.setColumnsToGet(columnsToGet);

SearchResponse response = client.search(request);
System.out.println(response.getTotalCount());
System.out.println(response.getRows());

Paramètres

Requête de recherche

Le paramètre request est un objet SearchRequest qui contient les paramètres suivants.

Nom	Type	Description
tableName (obligatoire)	String	Nom de la table.
indexName (obligatoire)	String	Nom de l'index de recherche.
searchQuery (obligatoire)	SearchQuery	Condition de requête et paramètres courants de requête.
columnsToGet (facultatif)	SearchRequest.ColumnsToGet	Paramètres des colonnes renvoyées. Si vous omettez ce paramètre, seules les colonnes de clé primaire sont renvoyées.
timeoutInMillisecond (facultatif)	int	Délai d'expiration de la requête au niveau de la demande, en millisecondes. La valeur par défaut est `-1`, ce qui signifie qu'aucun délai d'expiration distinct n'est appliqué à la requête.
routingValues (facultatif)	`List<PrimaryKey>`	Valeurs de clé primaire pour les champs de routage personnalisé. Omettez ce paramètre si l'index n'utilise pas le routage personnalisé.

Paramètres de requête

Le paramètre request.searchQuery est un objet SearchQuery qui contient les paramètres suivants.

Nom	Type	Description
query (obligatoire)	Query	Condition de requête. Définissez ce paramètre sur `TermsQuery` pour une requête par termes.
offset (facultatif)	Integer	Position de départ de la requête.
limit (facultatif)	Integer	Nombre maximal de lignes à renvoyer. Définissez ce paramètre sur `0` pour ne renvoyer aucune ligne.
highlight (facultatif)	Highlight	Paramètres de résumé et de mise en évidence pour les champs Text. Pour plus de détails sur la configuration, voir Résumé et mise en évidence.
collapse (facultatif)	Collapse	Paramètres de regroupement de champs, permettant de dédupliquer les résultats selon un champ spécifié. Pour plus de détails sur la configuration, voir Regrouper les résultats de requête.
sort (facultatif)	Sort	Ordre de tri des résultats. Pour plus de détails sur la configuration, voir Trier et paginer les résultats.
trackTotalCount (facultatif)	int	Nombre maximal attendu de lignes correspondantes à comptabiliser. La valeur par défaut est `TRACK_TOTAL_COUNT_DISABLED`, ce qui désactive le comptage. Définissez ce paramètre sur `TRACK_TOTAL_COUNT` pour compter toutes les lignes correspondantes. Une valeur plus faible améliore les performances de la requête.
filter (facultatif)	SearchFilter	Filtre appliqué aux résultats de `query`.
aggregationList (facultatif)	`List<Aggregation>`	Paramètres d'agrégation. Pour plus de détails sur la configuration, voir Agrégation.
groupByList (facultatif)	`List<GroupBy>`	Paramètres de regroupement. Pour plus de détails sur la configuration, voir Agrégation.
token (facultatif)	byte[]	Jeton de pagination. Définissez ce paramètre avec la valeur `nextToken` issue de la réponse précédente pour poursuivre la lecture des lignes. Lorsque vous définissez `token`, le SDK efface `sort` car le jeton contient déjà les conditions de tri.

Condition de requête

Le paramètre request.searchQuery.query est un objet TermsQuery qui contient les paramètres suivants.

Nom	Type	Description
fieldName (obligatoire)	String	Nom du champ indexé à interroger.
terms (obligatoire)	`List<ColumnValue>`	Termes de recherche. Vous pouvez spécifier jusqu'à 1 024 valeurs. Une ligne correspond si n'importe quel terme satisfait la condition de correspondance exacte. Pour un champ Text, chaque valeur est utilisée comme un terme 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 accroît la contribution de la condition de requête au score de pertinence BM25. Ce paramètre n'affecte ni la correspondance ni le nombre de lignes renvoyées. Il influe sur l'ordre des résultats uniquement lorsque `ScoreSort` est utilisé pour trier par score de pertinence. Valeur par défaut : `1.0`.

Colonnes renvoyées

Le paramètre request.columnsToGet est un objet SearchRequest.ColumnsToGet qui contient les paramètres suivants.

Nom	Type	Description
columns (facultatif)	`List<String>`	Colonnes d'attribut à renvoyer. Définissez ce paramètre uniquement si `returnAll` et `returnAllFromIndex` sont tous deux définis sur `false`. Si vous omettez ce paramètre, seules les colonnes de clé primaire sont renvoyées.
returnAll (facultatif)	boolean	Indique s'il faut renvoyer toutes les colonnes d'attribut de la table. Valeur par défaut : `false`.
returnAllFromIndex (facultatif)	boolean	Indique s'il faut renvoyer toutes les colonnes d'attribut indexées. Valeur par défaut : `false`. Ce paramètre et `returnAll` ne peuvent pas être simultanément définis sur `true`.

Valeurs de retour

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

Nom	Type	Description
totalCount	long	Nombre de lignes correspondantes. Appelez `getTotalCount()` pour obtenir la valeur. La valeur renvoyée dépend du paramètre `trackTotalCount`.
rows	`List<Row>`	Lignes renvoyées par cette requête. Appelez `getRows()` pour obtenir la valeur. Le nombre de lignes ne dépasse pas `limit`.
searchHits	`List<SearchHit>`	Résultats de la requête. Appelez `getSearchHits()` pour obtenir la valeur. Si `highlight` est configuré, ce champ contient les données de ligne ainsi que les résultats de résumé et de mise en évidence.
nextToken	byte[]	Jeton de page suivante. Appelez `getNextToken()` pour obtenir la valeur. Si la valeur n'est pas `null`, définissez-la comme `token` dans la requête suivante pour poursuivre la lecture des lignes.
isAllSuccess	boolean	Indique si toutes les partitions d'index ont été interrogées avec succès. Appelez `isAllSuccess()` pour obtenir la valeur. Si la valeur est `false`, la réponse contient des résultats partiels et `totalCount` peut être inférieur au nombre réel de lignes correspondantes.