Suffix query - Tablestore SDK for Java - Tablestore - Alibaba Cloud Documentation Center

Prerequisites

Install the Tablestore SDK for Java and initialize a client.

Note

Suffix queries require Tablestore SDK for Java 5.17.0 or later.

Feature description

A suffix query matches complete field values that end with a specified string. Suffix queries support only FuzzyKeyword fields. For more information about this field type, see String types. Matching is case-sensitive. For example, the field value order-H001 matches the suffix H001 but not h001.

Note

FuzzyKeyword fields do not support sorting or aggregation. If the same query requires sorting or aggregation, use a different field that supports the required operation.

Keyword fields do not support SuffixQuery. To implement equivalent suffix matching, reverse the field value before you write it to a Keyword field that is used for queries. At query time, reverse the suffix string to match and run a prefix query (PrefixQuery) on the field.

Set the query type to SuffixQuery when you call search. Use SearchQuery to configure the result limit, total count tracking, and other general query settings.

SearchResponse search(SearchRequest request)

The following example queries FuzzyKeyword values in the phone field that end with 1234. The query returns up to 10 rows and the total number of matches.

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

SuffixQuery suffixQuery = new SuffixQuery();
suffixQuery.setFieldName("phone");
suffixQuery.setSuffix("1234");

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(suffixQuery);
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());

Parameters

Search request

request is a SearchRequest object that contains the following parameters.

Name	Type	Description
tableName (required)	String	The name of the data table.
indexName (required)	String	The name of the search index.
searchQuery (required)	SearchQuery	The query condition and general query settings.
columnsToGet (optional)	SearchRequest.ColumnsToGet	The columns to return. If this parameter is not configured, only primary key columns are returned.
timeoutInMillisecond (optional)	int	The request-level query timeout in milliseconds. The default value is `-1`, which does not configure a separate query timeout.
routingValues (optional)	`List<PrimaryKey>`	The primary key values that correspond to custom routing fields. Leave this parameter unset if custom routing is not configured.

Query settings

request.searchQuery is a SearchQuery object that contains the following parameters.

Name	Type	Description
query (required)	Query	The query condition. Set this parameter to a `SuffixQuery` object for a suffix query.
offset (optional)	Integer	The position from which to start the current query.
limit (optional)	Integer	The maximum number of rows to return. Set this parameter to `0` to return no rows.
collapse (optional)	Collapse	The collapse configuration used to deduplicate results by a specified field. For more information, see Collapse (distinct).
sort (optional)	Sort	The sort order of the results. `FuzzyKeyword` fields cannot be used as sort fields. For more information, see Sorting and pagination.
trackTotalCount (optional)	int	The maximum number of matching rows to count. The default value is `TRACK_TOTAL_COUNT_DISABLED`, which disables counting. Set this parameter to `TRACK_TOTAL_COUNT` to count all matching rows. A smaller value provides better query performance.
filter (optional)	SearchFilter	A post-query filter applied to the results of `query`.
aggregationList (optional)	`List<Aggregation>`	The aggregation configurations. `FuzzyKeyword` fields cannot be used as aggregation fields. For more information, see Aggregation.
groupByList (optional)	`List<GroupBy>`	The grouping configurations. `FuzzyKeyword` fields cannot be used as grouping fields. For more information, see Aggregation.
token (optional)	byte[]	The pagination token. Set the `nextToken` from the previous response as this parameter to read the next page. When `token` is set, the SDK clears `sort` because the token already contains the sort condition.

Query condition

request.searchQuery.query is a SuffixQuery object that contains the following parameters.

Name	Type	Description
fieldName (required)	String	The name of the `FuzzyKeyword` field to query.
suffix (required)	String	The query string. The complete field value must end with this string. Matching is case-sensitive.
weight (optional)	float	The relevance weight of the query condition. The value must be a positive floating-point number. A larger value gives the condition more influence on the BM25 relevance score. This parameter does not change which rows match or how many rows are returned. It affects result order only when `ScoreSort` is used. The default value is `1.0`.

Returned columns

request.columnsToGet is a SearchRequest.ColumnsToGet object that contains the following parameters.

Name	Type	Description
columns (optional)	`List<String>`	The attribute columns to return. Configure this parameter only if both `returnAll` and `returnAllFromIndex` are `false`. If this parameter is not configured, only primary key columns are returned.
returnAll (optional)	boolean	Specifies whether to return all attribute columns from the data table. The default value is `false`.
returnAllFromIndex (optional)	boolean	Specifies whether to return all indexed attribute columns. The default value is `false`. Do not set both `returnAll` and `returnAllFromIndex` to `true`.

Return values

search returns a SearchResponse object. The following table describes the main fields.

Name	Type	Description
totalCount	long	The number of matching rows, obtained by calling `getTotalCount()`. The returned value depends on the `trackTotalCount` setting.
rows	`List<Row>`	The rows returned by the current query, obtained by calling `getRows()`. The number of rows does not exceed `limit`.
nextToken	byte[]	The token for the next page, obtained by calling `getNextToken()`. If the value is not `null`, set it as `token` in the next request to continue reading.
isAllSuccess	boolean	Indicates whether all index partitions were queried successfully, obtained by calling `isAllSuccess()`. If this value is `false`, the response contains partial results and `totalCount` may be less than the actual number of matches.