Match query

A match query with the Tablestore SDK for Java searches Text or Keyword fields and returns rows that satisfy the matching conditions with relevance scores.

Prerequisites

Install the Tablestore SDK for Java and initialize the client.

Feature description

A match query searches Text or Keyword fields. For information about the field types, see String types. The two field types use different matching behavior:

Text: The field value and query text are analyzed by using the analyzer configured when the search index is created. If no analyzer is configured, single-word tokenization is used by default. The default OR operator matches a field value that contains any query token. You can use the AND operator to require all query tokens or specify the minimum number of tokens that must match.
Keyword: Neither the field value nor the query text is analyzed. A row matches only if the complete field value equals the query text.

A match query does not require matching tokens to be adjacent or in the same order as the query text. To match tokens in order, use a match phrase query. If a Text field uses the fuzzy analyzer and you need high-performance fuzzy search, a match phrase query is also recommended.

The following example queries rows whose description field contains the tablestore or durable token and returns up to 10 rows, the total number of matching rows, and relevance scores.

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

MatchQuery matchQuery = new MatchQuery();
matchQuery.setFieldName("description");
matchQuery.setText("tablestore durable");

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(matchQuery);
searchQuery.setSort(new Sort(Collections.singletonList(new ScoreSort())));
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);
for (SearchHit hit : response.getSearchHits()) {
    System.out.println(hit.getRow());
    System.out.println(hit.getScore());
}

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 `MatchQuery` for a match 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.

Match condition

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

Name	Type	Description
fieldName (required)	String	The name of the `Text` or `Keyword` index field to query.
text (required)	String	The query text. For a `Text` field, the query text is analyzed by using the field analyzer. For a `Keyword` field, the query text is not analyzed.
operator (optional)	QueryOperator	The operator used to combine query tokens. `OR` (default) matches a row if any token matches. `AND` requires all tokens to match.
minShouldMatch (optional)	String or int	The minimum number of query tokens that must match when `operator` is `OR`. Specify an integer such as `2` or a percentage string such as `"75%"`.
weight (optional)	float	The query weight. The default value is `1.0` and the value must be a positive floating-point number. A larger value increases this query's contribution to the relevance score without changing the matching scope.

Important

setMinimumShouldMatch(Integer) is deprecated. Use setMinShouldMatch(int) or setMinShouldMatch(String).

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 both `returnAll` and `returnAllFromIndex` are `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. The default value is `false`.
returnAllFromIndex (optional)	boolean	Specifies whether to return all indexed attribute columns. The default value is `false`. This parameter and `returnAll` cannot both be `true`.

Return values

Query response

The search method returns a SearchResponse object. The following table describes the main 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 in the current response. 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. This field contains relevance scores 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.

Query hit

response.searchHits[] is a SearchHit object that contains the following main fields.

Name	Type	Description
row	Row	The matching row. Call `getRow()` to obtain the value.
score	Double	The relevance score. Call `getScore()` to obtain the value. When `ScoreSort` is used, this field contains the actual score. Matching tokens and `weight` affect the score.
highlightResultItem	HighlightResultItem	The summary and highlighting result. Call `getHighlightResultItem()` to obtain the value.

Examples

Match all query tokens

Set operator to AND to match a row only if the field value contains all query tokens.

MatchQuery matchQuery = new MatchQuery();
matchQuery.setFieldName("description");
matchQuery.setText("tablestore durable");
matchQuery.setOperator(QueryOperator.AND);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(matchQuery);

Set the minimum number of matching tokens

When the OR operator is used, set minShouldMatch to specify the minimum number of query tokens that must match. The following example requires at least two matching tokens.

MatchQuery matchQuery = new MatchQuery();
matchQuery.setFieldName("description");
matchQuery.setText("tablestore durable cloud");
matchQuery.setOperator(QueryOperator.OR);
matchQuery.setMinShouldMatch(2);

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(matchQuery);