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

Prerequisites

Install the Tablestore SDK for Java and initialize a client.

Feature description

An exists query (ExistsQuery, also called a NULL query or null-value query) matches rows in which a specified indexed field exists. A field does not exist if the corresponding column is not written to the data table. An empty array is also treated as a nonexistent array field.

When you call search, set the query type to ExistsQuery and specify a field name. To query a Nested parent field or subfield, wrap ExistsQuery in a NestedQuery. To match rows in which a field does not exist, add ExistsQuery to BoolQuery.mustNotQueries.

SearchResponse search(SearchRequest request)

The following example queries rows in which the city field exists. The query returns up to 10 rows and the total number of matches.

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

ExistsQuery existsQuery = new ExistsQuery();
existsQuery.setFieldName("city");

SearchQuery searchQuery = new SearchQuery();
searchQuery.setQuery(existsQuery);
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 an `ExistsQuery` object for an exists 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.
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 an ExistsQuery object that contains the following parameter.

Name	Type	Description
fieldName (required)	String	The name of the indexed field to query.

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 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.
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.

Scenario examples

Query rows in which a field does not exist

Add ExistsQuery to BoolQuery.mustNotQueries to match rows in which the city field does not exist.

ExistsQuery existsQuery = new ExistsQuery();
existsQuery.setFieldName("city");

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

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

Query a Nested field

Wrap ExistsQuery in a NestedQuery. To query the parent field, set fieldName to items. To query a subfield, specify the full path, such as items.keyword. The following example queries rows in which the items.keyword subfield exists.

ExistsQuery existsQuery = new ExistsQuery();
existsQuery.setFieldName("items.keyword");

NestedQuery nestedQuery = new NestedQuery();
nestedQuery.setPath("items");
nestedQuery.setQuery(existsQuery);
nestedQuery.setScoreMode(ScoreMode.None);

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