Prefix query

Prerequisites

Install the Tablestore SDK for Java and initialize the client.

Feature description

A prefix query matches field values or tokens in a specified field that start with the query string. For Keyword and FuzzyKeyword fields (see String types), the entire field value must start with the query string, and matching is case-sensitive. For a Text field, a row matches if any token produced by the analyzer starts with the query string. The query string itself is not tokenized.

Note

For large datasets, use the FuzzyKeyword type, which is optimized for fuzzy queries. Prefix query performance on a Keyword field decreases as the indexed data grows, so use this type only for small datasets. The Text type is supported for compatibility. Tokenization makes its results configuration-dependent and unsuitable for matching complete strings.

To call search, set the query type to PrefixQuery, and use SearchQuery to configure the number of returned rows, total count tracking, and other common query behaviors.

SearchResponse search(SearchRequest request)

The following example queries rows whose category field is of the FuzzyKeyword type and starts with hang. The query returns up to 10 rows and the total number of matching rows.

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

PrefixQuery prefixQuery = new PrefixQuery();
prefixQuery.setFieldName("category");
prefixQuery.setPrefix("hang");

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(prefixQuery);
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 table.
indexName (required)	String	The name of the search index.
searchQuery (required)	SearchQuery	The query condition and common query settings.
columnsToGet (optional)	SearchRequest.ColumnsToGet	The returned column settings. If you omit this parameter, only primary key columns are returned.
timeoutInMillisecond (optional)	int	The request-level query timeout in milliseconds. The default value is `-1`, which does not set a separate query timeout.
routingValues (optional)	`List<PrimaryKey>`	The primary key values for custom routing fields. Omit this parameter if the index does not use custom routing.

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 `PrefixQuery` for a prefix query.
offset (optional)	Integer	The starting position of the query.
limit (optional)	Integer	The maximum number of rows to return. Set this parameter to `0` to return no rows.
highlight (optional)	Highlight	The summary and highlighting settings for Text fields. For configuration details, see Summary and highlighting.
collapse (optional)	Collapse	The field collapse settings, which deduplicate results by a specified field. For configuration details, see Collapse query results.
sort (optional)	Sort	The result sort order. For configuration details, see Sort and paginate results.
trackTotalCount (optional)	int	The expected 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 improves query performance.
filter (optional)	SearchFilter	A filter that is applied to the results of `query`.
aggregationList (optional)	`List<Aggregation>`	The aggregation settings. For configuration details, see Aggregation.
groupByList (optional)	`List<GroupBy>`	The grouping settings. For configuration details, see Aggregation.
token (optional)	byte[]	The pagination token. Set this parameter to the `nextToken` value from the previous response to continue reading rows. When you set `token`, the SDK clears `sort` because the token already contains the sort conditions.

Query condition

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

Name	Type	Description
fieldName (required)	String	The name of the indexed field to query.
prefix (required)	String	The query string. For a `Keyword` or `FuzzyKeyword` field, the field value must start with this string. For a `Text` field, at least one token must start with this string. The query string itself is not tokenized.
weight (optional)	float	The relevance weight of the query condition. The value must be a positive floating-point number. A larger value gives the query condition a greater contribution to the BM25 relevance score. This parameter does not affect matching or the number of rows returned. It affects result order only when `ScoreSort` is used to sort by relevance score. Default value: `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. Set this parameter only if `returnAll` and `returnAllFromIndex` are both `false`. If you omit this parameter, only primary key columns are returned.
returnAll (optional)	boolean	Specifies whether to return all attribute columns in the table. Default value: `false`.
returnAllFromIndex (optional)	boolean	Specifies whether to return all indexed attribute columns. Default value: `false`. This parameter and `returnAll` cannot both be `true`.

Return values

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

Name	Type	Description
totalCount	long	The number of matching rows. Call `getTotalCount()` to obtain the value. The returned value depends on the `trackTotalCount` setting.
rows	`List<Row>`	The rows returned by this query. Call `getRows()` to obtain the value. The number of rows does not exceed `limit`.
searchHits	`List<SearchHit>`	The query hits. Call `getSearchHits()` to obtain the value. If `highlight` is configured, this field contains the row data and summary and highlighting results.
nextToken	byte[]	The next-page token. Call `getNextToken()` to obtain the value. If the value is not `null`, set it as `token` in the next request to continue reading rows.
isAllSuccess	boolean	Indicates whether all index partitions were queried successfully. Call `isAllSuccess()` to obtain the value. If the value is `false`, the response contains partial results and `totalCount` may be less than the actual number of matching rows.