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

Prerequisites

Install the Tablestore SDK for Java and initialize a client.

Feature description

A Boolean query uses BoolQuery to combine one or more subqueries into a complex query condition. A subquery can be any Query type, including another BoolQuery.

BoolQuery supports the following clause types:

mustQueries: A row must match all subqueries. Matching subqueries contribute to the relevance score. This clause type is equivalent to AND.
filterQueries: A row must match all subqueries, but matching subqueries do not contribute to the relevance score. This clause type is also equivalent to AND.
shouldQueries: A row must match at least the number of subqueries specified by minShouldMatch. Matching more subqueries produces a higher relevance score. This clause type is equivalent to OR.
mustNotQueries: A row must not match any subquery. This clause type is equivalent to NOT and does not contribute to the relevance score.

If minShouldMatch is not configured and the Boolean query contains only shouldQueries and mustNotQueries, at least one shouldQueries subquery must match. If the Boolean query contains mustQueries or filterQueries at the same level, the shouldQueries subqueries are optional by default.

Call search to perform a Boolean query.

SearchResponse search(SearchRequest request)

The following example queries rows in which city is equal to hangzhou and category is equal to book. The query returns up to 10 rows and the total number of matches.

String tableName = "example_table";
String indexName = "example_index";
TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustQueries(Arrays.asList(cityQuery, categoryQuery));

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(boolQuery);
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.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 `BoolQuery` object for a Boolean 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 highlight settings when a subquery matches a Text field. 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.

Boolean query condition

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

Name	Type	Description
mustQueries (optional)	`List<Query>`	The subqueries that a row must all match. Matching subqueries contribute to the relevance score. This clause type is equivalent to AND.
filterQueries (optional)	`List<Query>`	The subqueries that a row must all match. Matching subqueries do not contribute to the relevance score. This clause type is equivalent to AND.
shouldQueries (optional)	`List<Query>`	The subqueries of which a specified minimum number must match. This clause type is equivalent to OR. Matching more subqueries produces a higher relevance score.
mustNotQueries (optional)	`List<Query>`	The subqueries of which none can match. This clause type is equivalent to NOT and does not contribute to the relevance score.
minShouldMatch (optional)	String or int	The minimum number of `shouldQueries` subqueries that must match. Specify an integer, such as `2`, or a percentage string, such as `"75%"`. If this parameter is omitted, the default value is `0` when `mustQueries` or `filterQueries` exists at the same level. In other cases that contain `shouldQueries`, the default value is `1`.
weight (optional)	Float	The weight of the Boolean query. If this parameter is omitted, the query uses a weight of `1.0`. A larger value increases the contribution of `mustQueries` and `shouldQueries` to the final relevance score without changing which rows match.

Note

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 `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 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 response

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. Read relevance scores and summary and highlight results from this field.
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.

Search hit

response.searchHits[] is a SearchHit object that contains the following core 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 you use `ScoreSort` to sort by relevance score, this field contains the actual score.
highlightResultItem	HighlightResultItem	The summary and highlight result. Call `getHighlightResultItem()` to obtain the value.

Scenario examples

Match any condition

Use shouldQueries to combine conditions and minShouldMatch to specify the minimum number of conditions that must match. The following example queries rows in which city is equal to hangzhou or category is equal to book.

TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setShouldQueries(Arrays.asList(cityQuery, categoryQuery));
boolQuery.setMinShouldMatch(1);

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

Exclude rows that match a condition

Use mustNotQueries to exclude rows that match any specified condition. The following example queries rows in which city is not equal to hangzhou.

TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setMustNotQueries(Collections.singletonList(cityQuery));

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

Filter by multiple conditions without relevance scoring

Use filterQueries to require all subqueries to match without allowing the conditions to contribute to the relevance score. The following example queries rows in which city is equal to hangzhou and category is equal to book.

TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setFilterQueries(Arrays.asList(cityQuery, categoryQuery));

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

Nest combinations of conditions

Use a BoolQuery as a subquery of another BoolQuery to express multi-level logic. The following example implements (city = "hangzhou" OR price < 150) OR (category = "book" AND (price = 300 OR price = 400)).

TermQuery cityQuery = new TermQuery();
cityQuery.setFieldName("city");
cityQuery.setTerm(ColumnValue.fromString("hangzhou"));

RangeQuery lowPriceQuery = new RangeQuery();
lowPriceQuery.setFieldName("price");
lowPriceQuery.lessThan(ColumnValue.fromLong(150));

BoolQuery firstGroup = new BoolQuery();
firstGroup.setShouldQueries(Arrays.asList(cityQuery, lowPriceQuery));

TermQuery price300Query = new TermQuery();
price300Query.setFieldName("price");
price300Query.setTerm(ColumnValue.fromLong(300));

TermQuery price400Query = new TermQuery();
price400Query.setFieldName("price");
price400Query.setTerm(ColumnValue.fromLong(400));

BoolQuery priceGroup = new BoolQuery();
priceGroup.setShouldQueries(Arrays.asList(price300Query, price400Query));

TermQuery categoryQuery = new TermQuery();
categoryQuery.setFieldName("category");
categoryQuery.setTerm(ColumnValue.fromString("book"));

BoolQuery secondGroup = new BoolQuery();
secondGroup.setMustQueries(Arrays.asList(categoryQuery, priceGroup));

BoolQuery boolQuery = new BoolQuery();
boolQuery.setShouldQueries(Arrays.asList(firstGroup, secondGroup));

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