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

Prerequisites

Install the Tablestore SDK for Python and initialize a client.

Description

A Boolean query uses BoolQuery to combine multiple child queries into a complex condition. A child query can be any query type or another BoolQuery. must_queries and filter_queries represent AND, should_queries represents OR, and must_not_queries represents NOT. filter_queries and must_not_queries do not contribute to relevance scores.

If minimum_should_match is not specified, should_queries is optional when must_queries or filter_queries exists at the same level. In other cases that contain should_queries, at least one should_queries child query must match by default.

BoolQuery(
    must_queries=None,
    must_not_queries=None,
    filter_queries=None,
    should_queries=None,
    minimum_should_match=None,
    weight=None,
)

The following example queries rows in which city is hangzhou and category is book.

query = BoolQuery(
    must_queries=[
        TermQuery("city", "hangzhou"),
        TermQuery("category", "book"),
    ]
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10, get_total_count=True),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)

Parameters

Search request

The search method contains the following parameters.

Name	Type	Description
table_name (required)	`str`	The name of the data table.
index_name (required)	`str`	The name of the search index.
search_query (required)	`SearchQuery`	The query condition and common query configurations.
columns_to_get (optional)	`ColumnsToGet`	The return column configuration. If this parameter is not specified, only primary key columns are returned.
routing_keys (optional)	`list`	The primary key values of custom routing fields. This parameter is not required if custom routing is not configured.
timeout_s (optional)	`int`	The request timeout in seconds. If this parameter is not specified, the client-level timeout is used.

Query configuration

search_query is of the SearchQuery type and contains the following parameters.

Name	Type	Description
query (required)	`Query`	The query condition. Set this parameter to `BoolQuery`.
sort (optional)	`Sort`	The sort order of results. For more information, see Sort and paginate results.
get_total_count (optional)	`bool`	Specifies whether to return the total number of matching rows. Default value: `False`. Setting this parameter to `True` increases query overhead.
next_token (optional)	`bytes`	The pagination token. Pass `next_token` from the previous response to retrieve the next page.
offset (optional)	`int`	The offset from which the query starts. Use this parameter for shallow pagination.
limit (optional)	`int`	The maximum number of rows to return. If this parameter is set to `0`, no rows are returned.
aggs (optional)	`list[Agg]`	The metric aggregation configurations. For more information, see Aggregation.
group_bys (optional)	`list[BaseGroupBy]`	The grouping configurations. For more information, see Aggregation.
collapse_field (optional)	`Collapse`	The result collapse configuration. For more information, see Collapse query results.
highlight (optional)	`Highlight`	The summary and highlighting configuration for `Text` fields. For more information, see Summary and highlighting.

Boolean query condition

search_query.query is of the BoolQuery type and contains the following parameters.

Name	Type	Description
must_queries (optional)	`list[Query]`	The child queries that must all match. Matching child queries contribute to relevance scores.
filter_queries (optional)	`list[Query]`	The child queries that must all match but do not contribute to relevance scores.
should_queries (optional)	`list[Query]`	The child queries of which a specified minimum number must match. Matching more conditions increases the relevance score.
must_not_queries (optional)	`list[Query]`	The child queries that must not match. They do not contribute to relevance scores.
minimum_should_match (optional)	`int`	The minimum number of `should_queries` child queries that must match.
weight (optional)	`float`	The query weight, which must be a positive floating-point number. Default value: `1.0`. This parameter affects relevance scores but not matching.

Return columns

columns_to_get is of the ColumnsToGet type and contains the following parameters.

Name	Type	Description
column_names (optional)	`list[str]`	The names of attribute columns to return. Specify this parameter only when `return_type` is `SPECIFIED`.
return_type (optional)	`ColumnReturnType`	The return column mode. `NONE` (default) returns only primary key columns; `SPECIFIED` returns specified attribute columns; `ALL` returns all attribute columns in the table; and `ALL_FROM_INDEX` returns all stored fields in the index.

Response

The search method returns SearchResponse. The following table describes the core fields.

Field	Type	Description
rows	`list[Row]`	The rows returned by the query. The number does not exceed `limit`.
next_token	`bytes`	The token for the next page. An empty value indicates that no more data is available.
total_count	`int`	The number of matching rows. The value depends on `get_total_count`.
is_all_succeed	`bool`	Indicates whether all index partitions were queried. If the value is `False`, partial results are returned.
agg_results	`list[AggResult]`	The metric aggregation results. This field is empty if `aggs` is not configured.
group_by_results	`list[GroupByResult]`	The grouping results. This field is empty if `group_bys` is not configured.
search_hits	`list[SearchHit]`	The search hits, including extended information such as rows, relevance scores, and highlights.

Tuple-compatible response

Starting from Tablestore SDK for Python 5.2.0, search APIs return response objects instead of tuples. Version 5.1.0 and earlier return tuples directly. In version 5.2.1 and later, you can call SearchResponse.v1_response() to obtain a tuple compatible with earlier versions. For new code, access SearchResponse attributes directly to avoid unpacking errors if response fields are extended.

(
    rows,
    next_token,
    total_count,
    is_all_succeed,
    agg_results,
    group_by_results,
    search_hits,
) = response.v1_response()

Examples

Combine OR, NOT, and filter conditions

The following example requires rows to belong to a book- category, match at least one of the Python and Java categories, and not have the deprecated status.

query = BoolQuery(
    filter_queries=[PrefixQuery("category", "book-")],
    should_queries=[
        TermQuery("category", "book-python"),
        TermQuery("category", "book-java"),
    ],
    must_not_queries=[TermQuery("status", "deprecated")],
    minimum_should_match=1,
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
)
print(response.rows)