Table Store Python SDK 統計彙總 - Tablestore

使用 Tablestore Python SDK 可對多元索引查詢結果執行指標彙總和分組統計。

前提條件

統計彙總功能需要使用 5.2.1 及以上版本，建議使用最新版本的 SDK。

功能說明

統計彙總基於多元索引查詢的匹配結果計算指標或產生分組。將指標彙總對象添加到 SearchQuery.aggs，將分組對象添加到 SearchQuery.group_bys；同一請求中的 name 必須唯一，用於從響應中識別結果。只擷取統計結果時，可將 limit 設定為 0。

功能	說明
Min、Max、Sum、Avg	計算最小值、最大值、總和和平均值。
Count、DistinctCount	統計欄位非空值行數和不同值數量。
Percentiles	計算一個或多個百分位值。
TopRows	作為子彙總返回每個分組內排序靠前的行。
GroupByField、GroupByComposite	按單個欄位值或多個欄位組合分組。
GroupByRange、GroupByGeoDistance、GroupByFilter	按數值範圍、地理距離或過濾條件分組。
GroupByHistogram、GroupByDateHistogram、GroupByGeoGrid	產生數值長條圖、日期長條圖或 GeoHash 網格分組。

重要

用於統計彙總的多元索引欄位必須啟用排序與統計彙總。不同彙總和分組支援的欄位類型不同。同一層級最多配置 5 個分組。去重行數、百分位元和欄位值分組採用近似計算；彙總數量多或嵌套層級深會增加請求複雜度並影響響應速度。

以下樣本對 price 欄位計算最小值、最大值和平均值，並按 category 分組統計行數。

search_query = SearchQuery(
    MatchAllQuery(),
    limit=0,
    aggs=[
        Min("price", name="min_price"),
        Max("price", name="max_price"),
        Avg("price", name="avg_price"),
    ],
    group_bys=[
        GroupByField("category", name="by_category"),
    ],
)
response = client.search(
    "example_table",
    "example_index",
    search_query,
)
for result in response.agg_results:
    print(result.name, result.value)
for result in response.group_by_results:
    print(result.name, result.items)

參數說明

查詢請求

search 方法包含以下參數。

名稱	類型	說明
table_name（必選）	`str`	資料表名稱。
index_name（必選）	`str`	多元索引名稱。
search_query（必選）	`SearchQuery`	查詢條件和統計彙總配置。
columns_to_get（可選）	`ColumnsToGet`	返回列配置。未設定時只返回主鍵列。
routing_keys（可選）	`list`	自訂路由欄位對應的主索引值列表。未配置自訂路由時無需設定。
timeout_s（可選）	`int`	請求級逾時時間，單位為秒。未設定時使用用戶端預設逾時時間。

查詢配置

search_query 的類型為 SearchQuery，包含以下與統計彙總相關的參數。

名稱	類型	說明
query（必選）	`Query`	統計範圍對應的查詢條件。統計全部資料時設定為 `MatchAllQuery`。
aggs（可選）	`list[Agg]`	指標彙總列表，可組合多個不同名稱的彙總。
group_bys（可選）	`list[BaseGroupBy]`	分組列表，可組合多個不同名稱的分組。
limit（可選）	`int`	查詢返回行數。只擷取統計結果時設定為 `0`。

指標彙總

以下各對象添加到 search_query.aggs。field 為彙總欄位，name 為結果名稱，missing_value 表示欄位缺失時用於參與計算的值；未設定 missing_value 時忽略缺少該欄位的行。

Min、Max 和 Avg

名稱	類型	說明
field（必選）	`str`	彙總欄位，支援 `Long`、`Double` 和 `Date`。
missing_value（可選）	`str / int / float`	欄位缺失時參與計算的值。
name（可選）	`str`	彙總名稱，預設分別為 `min`、`max` 和 `avg`。

Sum

名稱	類型	說明
field（必選）	`str`	彙總欄位，支援 `Long` 和 `Double`。
missing_value（可選）	`int / float`	欄位缺失時用於求和的值。
name（可選）	`str`	彙總名稱，預設值為 `sum`。

Count

名稱	類型	說明
field（必選）	`str`	要統計非空值行數的欄位，支援 `Long`、`Double`、`Boolean`、`Keyword`、`Date` 和 `GeoPoint`。
name（可選）	`str`	彙總名稱，預設值為 `count`。

DistinctCount

名稱	類型	說明
field（必選）	`str`	要統計不同值數量的欄位，支援 `Long`、`Double`、`Boolean`、`Keyword`、`Date` 和 `GeoPoint`。
missing_value（可選）	`str / int / float / bool`	欄位缺失時參與去重統計的值。
name（可選）	`str`	彙總名稱，預設值為 `distinct_count`。

Percentiles

名稱	類型	說明
field（必選）	`str`	彙總欄位，支援 `Long`、`Double` 和 `Date`。
percentiles_list（必選）	`list[float]`	要計算的百分位列表，例如 `[50, 90, 99]`。
missing_value（可選）	`str / int / float`	欄位缺失時參與計算的值。
name（可選）	`str`	彙總名稱，預設值為 `percentiles`。

TopRows

名稱	類型	說明
limit（必選）	`int`	每個分組內最多返回的行數。
sort（必選）	`Sort`	分組內行的排序方式。
name（可選）	`str`	彙總名稱，預設值為 `top_rows`。

說明

DistinctCount 為近似統計：不同值少於 10,000 時結果接近精確值；達到 1 億時誤差約為 2%。Percentiles 也為近似統計，較極端的百分位通常比中位元更準確。TopRows 僅作為分組的子彙總使用。

分組

以下各對象添加到 search_query.group_bys。sub_aggs 和 sub_group_bys 可分別對每個分組繼續執行子指標彙總和子分組。

GroupByField

名稱	類型	說明
field_name（必選）	`str`	分組欄位，支援 `Long`、`Double`、`Boolean`、`Keyword` 和 `Date`。
size（可選）	`int`	返回分組數，預設值為 `10`，最大值為 `2000`。
group_by_sort（可選）	`list`	分組定序。預設按行數降序，支援 `GroupKeySort`、`RowCountSort` 和 `SubAggSort`。
sub_aggs（可選）	`list[Agg]`	子指標彙總。
sub_group_bys（可選）	`list[BaseGroupBy]`	子分組。
name（可選）	`str`	分組名稱，預設值為 `group_by_field`。

GroupByComposite

名稱	類型	說明
sources（必選）	`list[BaseGroupBy]`	多欄位分組源，最多 32 個。支援 `GroupByField`、`GroupByHistogram` 和 `GroupByDateHistogram`。
size（可選）	`int`	返回分組數，預設值為 `10`，最大值為 `2000`。
next_token（可選）	`bytes`	下一頁分組憑證。首次請求不設定。
suggested_size（可選）	`int`	高吞吐計算情境的軟式節流，不能與 `size` 同時設定。
sub_aggs（可選）	`list[Agg]`	子指標彙總。
sub_group_bys（可選）	`list[BaseGroupBy]`	子分組。`GroupByComposite` 不能作為其他分組的子分組。
name（可選）	`str`	分組名稱，預設值為 `group_by_composite`。

GroupByRange

名稱	類型	說明
field_name（必選）	`str`	分組欄位，支援 `Long` 和 `Double`。
ranges（必選）	`list[tuple]`	左閉右開範圍列表，例如 `[(0, 100), (100, 200)]`。
sub_aggs（可選）	`list[Agg]`	子指標彙總。
sub_group_bys（可選）	`list[BaseGroupBy]`	子分組。
name（可選）	`str`	分組名稱，預設值為 `group_by_range`。

GroupByGeoDistance

名稱	類型	說明
field_name（必選）	`str`	`GeoPoint` 類型分組欄位。
origin（必選）	`GeoPoint`	中心點，構造參數依次為緯度和經度。
ranges（必選）	`list[tuple]`	距離範圍列表，單位為米，採用左閉右開區間。
sub_aggs（可選）	`list[Agg]`	子指標彙總。
sub_group_bys（可選）	`list[BaseGroupBy]`	子分組。
name（可選）	`str`	分組名稱，預設值為 `group_by_geo_distance`。

GroupByFilter

名稱	類型	說明
filters（必選）	`list[Query]`	過濾條件列表，結果順序與條件順序一致。
sub_aggs（可選）	`list[Agg]`	子指標彙總。
sub_group_bys（可選）	`list[BaseGroupBy]`	子分組。
name（可選）	`str`	分組名稱，預設值為 `group_by_filter`。

GroupByHistogram

名稱	類型	說明
field_name（必選）	`str`	分組欄位，支援 `Long` 和 `Double`。
interval（必選）	`int / float`	數值長條圖間隔。
field_range（必選）	`FieldRange`	統計範圍。`(max-min)/interval` 不能超過 `2000`。
missing_value（可選）	`int / float`	欄位缺失時參與長條圖統計的值。
min_doc_count（可選）	`int`	分組內最少行數，行數不足的桶不返回。
group_by_sort（可選）	`list`	分組定序。
sub_aggs（可選）	`list[Agg]`	子指標彙總。
sub_group_bys（可選）	`list[BaseGroupBy]`	子分組。
name（可選）	`str`	分組名稱，預設值為 `group_by_histogram`。

GroupByDateHistogram

名稱	類型	說明
field_name（必選）	`str`	`Date` 類型分組欄位。
interval（必選）	`DateTimeValue`	日期或時間間隔，由數值和 `DateTimeUnit` 組成。
field_range（必選）	`FieldRange`	統計範圍。雖然 Python 構造方法允許省略，但服務端要求必須設定。
missing（可選）	`str`	欄位缺失時參與日期長條圖統計的日期值。
min_doc_count（可選）	`int`	分組內最少行數，行數不足的桶不返回。
time_zone（可選）	`str`	時區，格式為 `+hh:mm` 或 `-hh:mm`，例如 `+08:00`。
group_by_sort（可選）	`list`	分組定序。
offset（可選）	`DateTimeValue`	桶邊界相對預設起點的位移量。
sub_aggs（可選）	`list[Agg]`	子指標彙總。
sub_group_bys（可選）	`list[BaseGroupBy]`	子分組。
name（可選）	`str`	分組名稱，預設值為 `group_by_date_histogram`。

GroupByGeoGrid

名稱	類型	說明
field_name（必選）	`str`	`GeoPoint` 類型分組欄位。
precision（必選）	`GeoHashPrecision`	GeoHash 網格精度，枚舉序號越大，網格越小。
size（可選）	`int`	返回的網格分組數。
sub_aggs（可選）	`list[Agg]`	子指標彙總。
sub_group_bys（可選）	`list[BaseGroupBy]`	子分組。
name（可選）	`str`	分組名稱，預設值為 `group_by_geo_grid`。

說明

GroupByComposite 需要使用 Python SDK 6.4.4 及以上版本。分組結果較多時，設定 size 並使用返回結果的 next_token 翻頁，直到憑證為空白。

返回列

columns_to_get 的類型為 ColumnsToGet，包含以下參數。

名稱	類型	說明
column_names（可選）	`list[str]`	要返回的屬性列名稱。僅 `return_type` 為 `SPECIFIED` 時設定。
return_type（可選）	`ColumnReturnType`	返回列模式。`NONE`（預設）僅返回主鍵列；`SPECIFIED` 返回指定屬性列；`ALL` 返回資料表全部屬性列；`ALL_FROM_INDEX` 返回索引中已儲存的全部屬性列。

傳回值

search 方法返回 SearchResponse。核心欄位如下。

欄位	類型	說明
rows	`list[Row]`	本次查詢返回的行資料，數量不超過 `limit`。
next_token	`bytes`	下一頁憑證。值為空白時表示沒有更多資料。
total_count	`int`	匹配行數，取決於 `get_total_count` 配置。
is_all_succeed	`bool`	是否已成功查詢全部索引分割區。值為 `False` 時返回的是部分結果。
agg_results	`list[AggResult]`	指標彙總結果。未配置 `aggs` 時為空白。
group_by_results	`list[GroupByResult]`	分組結果。未配置 `group_bys` 時為空白。
search_hits	`list[SearchHit]`	查詢命中結果，包含行資料、相關性得分和高亮結果等擴充資訊。

agg_results 中每項通過 name 和 value 標識彙總及其值；group_by_results 中每項通過 name 和 items 返回各分組鍵、行數、子彙總和子分組。GroupByComposite 結果還包含 source_group_by_names 和用於繼續讀取的 next_token；每個分組的 keys 為字串列表，與 sources 順序一致，欄位值為空白時對應位置為 None。

相容 Tuple 返回格式

Tablestore Python SDK 5.2.0 開始將查詢介面的傳回值由 Tuple 調整為響應對象，5.1.0 及以下版本直接返回 Tuple。5.2.1 及以上版本可調用 SearchResponse.v1_response() 擷取與舊版本相容的 Tuple。新代碼建議直接存取 SearchResponse 的屬性，避免返回欄位擴充後解包數量不匹配。

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

情境樣本

使用多欄位分組並翻頁

以下樣本按 category 和 price 組合分組，每次返回兩個分組。

sources = [
    GroupByField("category", name="category_source"),
    GroupByField("price", name="price_source"),
]
next_token = None
all_items = []

while True:
    group_by = GroupByComposite(
        sources,
        size=2,
        next_token=next_token,
        name="by_category_and_price",
    )
    response = client.search(
        "example_table",
        "example_index",
        SearchQuery(MatchAllQuery(), limit=0, group_bys=[group_by]),
    )
    result = response.group_by_results[0]
    all_items.extend(result.items)
    next_token = result.next_token
    if not next_token:
        break

for item in all_items:
    print(item.keys, item.row_count)

產生日期長條圖和地理網格

以下樣本按天產生日期長條圖，並按約 39 km × 19 km 的 GeoHash 網格劃分地理位置。

group_bys = [
    GroupByDateHistogram(
        "event_date",
        DateTimeValue(1, DateTimeUnit.DAY),
        field_range=FieldRange("2026-08-01", "2026-08-04"),
        name="by_day",
    ),
    GroupByGeoGrid(
        "location",
        GeoHashPrecision.GHP_39KM_19KM_4,
        name="by_geo_grid",
    ),
]
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(MatchAllQuery(), limit=0, group_bys=group_bys),
)
for result in response.group_by_results:
    print(result.name, result.items)