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

Prerequisites

Install the Tablestore SDK for Python and initialize a client.

Description

A nested query queries child rows in a Nested field. Each child row preserves the relationships among its fields. You cannot directly query a child field and must wrap the child query in NestedQuery. The path parameter specifies the path of the Nested field, and fields in the child query must use full paths. The child query can be any Query type. If multiple conditions must be satisfied by the same child row, use a BoolQuery that contains the conditions as the child query of one NestedQuery. If different child rows can satisfy different conditions, create one NestedQuery for each condition and combine them with an outer BoolQuery.

NestedQuery(path, query, score_mode=ScoreMode.NONE, inner_hits=None, weight=None)

The following example queries rows in which the same child row of the items Nested field has items.name equal to alice and items.age less than 40.

child_query = BoolQuery(
    must_queries=[
        TermQuery("items.name", "alice"),
        RangeQuery("items.age", range_to=40),
    ]
)
query = NestedQuery("items", child_query)
search_query = SearchQuery(
    query,
    limit=10,
    get_total_count=True,
)
response = client.search(
    "example_table",
    "example_index",
    search_query,
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.total_count)
for row in response.rows:
    print(row)

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 list of primary key values for custom routing fields. You do not need to specify this parameter 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 `NestedQuery`.
sort (optional)	`Sort`	The sort order of query 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. Set this parameter to `next_token` from the previous response to retrieve the next page. For more information, see Sort and paginate results.
offset (optional)	`int`	The offset from which the current 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 row data is returned.
aggs (optional)	`list[Agg]`	The 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 collapsing configuration, which removes duplicate results based on a specified field. For more information, see Collapse query results.

Query condition

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

Name	Type	Description
path (required)	`str`	The path of the Nested field. For a multilevel Nested field, specify the full path, such as `items.details`.
query (required)	`Query`	The query condition to run in the child rows at `path`. You can use any Query type. Child fields must use full paths, such as `items.name`.
score_mode (optional)	`ScoreMode`	The method used to calculate the parent-row score when multiple child rows match. `NONE` (default) does not calculate relevance scores. `AVG`, `MAX`, `MIN`, and `TOTAL` use the average, maximum, minimum, and sum of child-row scores.
inner_hits (optional)	`InnerHits`	The return, sort, pagination, and highlighting configurations for matching child rows. If this parameter is not specified, matching child-row details are not returned.
weight (optional)	`float`	The relevance weight of the query condition. The value must be a positive floating-point number. Default value: `1.0`.

Matching child rows

search_query.query.inner_hits is of the InnerHits type and contains the following parameters.

Name	Type	Description
sort (required)	`Sort`	The sort order of matching child rows. Set this parameter to `None` if sorting is not required.
offset (required)	`int`	The offset from which matching child rows are returned. Pass `None` if you do not want to specify a value.
limit (required)	`int`	The number of matching child rows to return. If you pass `None`, the server returns three child rows by default.
highlight (required)	`Highlight`	The summary and highlighting configuration for child fields. Set this parameter to `None` if highlighting is not required. For more information, see Summary and highlighting.

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 the attribute columns in `column_names`; `ALL` returns all attribute columns from the table; and `ALL_FROM_INDEX` returns all indexed attribute columns.

Response

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

Field	Type	Description
rows	`list[Row]`	The rows returned by the current query. The number of rows does not exceed `limit`.
next_token	`bytes`	The token for the next page. If this field is not empty, pass it to the next request to continue reading.
total_count	`int`	The number of matching rows. The value depends on the `get_total_count` configuration.
is_all_succeed	`bool`	Indicates whether all index partitions were queried. If the value is `False`, partial results are returned and `total_count` may be less than the actual number of matching rows.
agg_results	`list[AggResult]`	The 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 relevance scores, highlights, and matching child rows.

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

Return matching child rows and highlights

The following example queries nested child rows in which items.name equals alice and returns matching child rows and highlighted fragments. Highlight results are available at search_hits[].search_inner_hits[].search_hits[].highlight_result.

highlight = Highlight([HighlightParameter("items.name")])
inner_hits = InnerHits(
    sort=None,
    offset=0,
    limit=10,
    highlight=highlight,
)
query = NestedQuery(
    "items",
    TermQuery("items.name", "alice"),
    inner_hits=inner_hits,
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
)
for search_hit in response.search_hits:
    for inner_hit in search_hit.search_inner_hits:
        for child_hit in inner_hit.search_hits:
            print(child_hit.row)
            print(child_hit.highlight_result.highlight_fields)