統計彙總 - Tablestore

使用統計彙總功能可以實現求最小值、求最大值、求和、求平均值、統計行數、去重統計行數、按欄位值分組、按範圍分組、按地理位置分組、按過濾條件分組等操作；同時多個統計彙總功能可以組合使用，滿足複雜的查詢需求。

说明從Python SDK 5.2.1及以上版本開始支援統計彙總功能。

背景資訊

統計彙總的詳細功能請參見下表。


功能	說明
最小值	返回一個欄位中的最小值，類似於SQL中的min。
最大值	返回一個欄位中的最大值，類似於SQL中的max。
和	返回數值欄位的總數，類似於SQL中的sum。
平均值	返回數值欄位的平均值，類似於SQL中的avg。
統計行數	返回指定欄位值的數量或者多元索引資料總行數，類似於SQL中的count。
去重統計行數	返回指定欄位不同值的數量，類似於SQL中的count（distinct）。
百分位統計	百分位統計常用來統計一組資料的百分位分布情況，例如在日常系統營運中統計每次請求訪問的耗時情況時，需要關注系統請求耗時的P25、P50、P90、P99值等分布情況。
欄位值分組	根據一個欄位的值對查詢結果進行分組，相同的欄位值放到同一分組內，返回每個分組的值和該值對應的個數。说明當分組較大時，按欄位值分組可能會存在誤差。
範圍分組	根據一個欄位的範圍對查詢結果進行分組，欄位值在某範圍內放到同一分組內，返回每個範圍中相應的item個數。
地理位置分組	根據距離某一個中心點的範圍對查詢結果進行分組，距離差值在某範圍內放到同一分組內，返回每個範圍中相應的item個數。
過濾條件分組	按照過濾條件對查詢結果進行分組，擷取每個過濾條件匹配到的數量，返回結果的順序和添加過濾條件的順序一致。
長條圖統計	按照指定資料間隔對查詢結果進行分組，欄位值在相同範圍內放到同一分組內，返回每個分組的值和該值對應的個數。

前提條件

已初始化OTSClient。具體操作，請參見初始化。
已建立資料表並寫入資料。
已在資料表上建立多元索引。具體操作，請參見建立多元索引。

最小值

返回一個欄位中的最小值，類似於SQL中的min。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Long和Double類型。
missing	當某行資料中的欄位為空白時，欄位值的預設值。如果未設定missing值，則在統計彙總時會忽略該行。如果設定了missing值，則使用missing值作為欄位值的預設值參與統計彙總。

樣本

統計年齡為18歲的人中得分的最低分數。

query = TermQuery('age', 18)
agg = Min('score', name = 'min')

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=0, aggs=[agg]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for agg_result in search_response.agg_results:
    print('{\n"name":"%s",\n"value":%s\n}\n' % (agg_result.name, str(agg_result.value)))

最大值

返回一個欄位中的最大值，類似於SQL中的max。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Long和Double類型。
missing	當某行資料中的欄位為空白時，欄位值的預設值。如果未設定missing值，則在統計彙總時會忽略該行。如果設定了missing值，則使用missing值作為欄位值的預設值參與統計彙總。

樣本

統計年齡為18歲的人中得分的最高分數。如果某人沒有分數，則對應分數的預設值為0。

query = TermQuery('age', 18)
agg = Max('score', missing_value = 0, name = 'max')

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=0, aggs=[agg]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for agg_result in search_response.agg_results:
    print('{\n"name":"%s",\n"value":%s\n}\n' % (agg_result.name, str(agg_result.value)))

和

返回數值欄位的總數，類似於SQL中的sum。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Long和Double類型。
missing	當某行資料中的欄位為空白時，欄位值的預設值。如果未設定missing值，則在統計彙總時會忽略該行。如果設定了missing值，則使用missing值作為欄位值的預設值參與統計彙總。

樣本

統計年齡為18歲的所有人得分的總和。

query = TermQuery('age', 18)
agg = Sum('score', name = 'sum')

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=2, aggs=[agg]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for agg_result in search_response.agg_results:
    print('{\n"name":"%s",\n"value":%s\n}\n' % (agg_result.name, str(agg_result.value)))

平均值

返回數值欄位的平均值，類似於SQL中的avg。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Long和Double類型。
missing	當某行資料中的欄位為空白時，欄位值的預設值。如果未設定missing值，則在統計彙總時會忽略該行。如果設定了missing值，則使用missing值作為欄位值的預設值參與統計彙總。

樣本

統計年齡為18歲的所有人得分的平均分。

query = TermQuery('age', 18)
agg = Avg('score', name = 'avg')

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=2, aggs=[agg]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for agg_result in search_response.agg_results:
    print('{\n"name":"%s",\n"value":%s\n}\n' % (agg_result.name, str(agg_result.value)))

統計行數

返回指定欄位值的數量或者多元索引資料總行數，類似於SQL中的count。

说明通過如下方式可以統計多元索引資料總行數或者某個query匹配的行數。

使用統計彙總的count功能，在請求中設定count(*)。
使用query功能的匹配行數，在query中設定setGetTotalCount(true)；如果需要統計多元索引資料總行數，則使用MatchAllQuery。

如果需要擷取多元索引資料某列出現的次數，則使用count（列名），可應用於稀疏列的情境。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Long、Double、Boolean、Keyword和Geo_point類型。

樣本

統計年齡為18歲的人中參加考試有分數的人數。


query = TermQuery('age', 18)
agg = Count('score', name = 'count')

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=2, aggs=[agg]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for agg_result in search_response.agg_results:
    print('{\n"name":"%s",\n"value":%s\n}\n' % (agg_result.name, str(agg_result.value)))

去重統計行數

返回指定欄位不同值的數量，類似於SQL中的count（distinct）。

说明去重統計行數的計算結果是個近似值。

當去重統計行數小於1萬時，計算結果接近精確值。
當去重統計行數達到1億時，計算結果的誤差為2%左右。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Long、Double、Boolean、Keyword和Geo_point類型。
missing	當某行資料中的欄位為空白時，欄位值的預設值。如果未設定Missing值，則在統計彙總時會忽略該行。如果設定了Missing值，則使用Missing值作為欄位值的預設值參與統計彙總。

樣本

去重統計年齡為18歲的人中一共有多少種不同的姓名。

query = TermQuery('age', 18)
agg = DistinctCount('name', name = 'distinct_name')

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=2, aggs=[agg]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for agg_result in search_response.agg_results:
    print('{\n"name":"%s",\n"value":%s\n}\n' % (agg_result.name, str(agg_result.value)))

百分位統計

百分位統計常用來統計一組資料的百分位分布情況，例如在日常系統營運中統計每次請求訪問的耗時情況時，需要關注系統請求耗時的P25、P50、P90、P99值等分布情況。

说明百分位統計為非精確統計，對不同百分位元值的計算精確度不同，較為極端的百分位元值更加準確，例如1%或99%的百分位元值會比50%的百分位元值準確。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Long和Double類型。
percentiles	百分位分布例如50、90、99，可根據需要設定一個或者多個百分位。
missing_value	當某行資料中的欄位為空白時，欄位值的預設值。如果未設定missing_value值，則在統計彙總時會忽略該行。如果設定了missing_value值，則使用missing_value值作為欄位值的預設值參與統計彙總。

樣本

query = TermQuery('product', '10010')
agg = Percentiles('latency', percentiles_list = [50, 90, 95])

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=2, aggs=[agg]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for agg_result in search_response.agg_results:
    print('percentiles:%s' % agg_result.name)
    for item in agg_result.value:
        print('%s:%s' % (str(item.key), str(item.value)))

欄位值分組

根據一個欄位的值對查詢結果進行分組，相同的欄位值放到同一分組內，返回每個分組的值和該值對應的個數。

说明當分組較大時，按欄位值分組可能會存在誤差。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Long、Double、Boolean和Keyword類型。
size	返回的分組數量，預設值為10。最大值為2000。當分組數量超過2000時，只會返回前2000個分組。
group_by_sort	分組中的item定序，預設按照分組中item的數量降序排序，多個排序則按照添加的順序進行排列。支援的參數如下：按照值的字典序升序排列按照值的字典序降序排列按照行數升序排列按照行數降序排列按照子統計彙總結果中值升序排列按照子統計彙總結果中值降序排列
sub_aggs和sub_group_bys	子統計彙總，子統計彙總會根據分組內容再進行一次統計彙總分析。情境統計每個類別的商品數量，且統計每個類別價格的最大值和最小值。方法最外層的統計彙總是根據類別進行分組，再添加兩個子統計彙總求價格的最大值和最小值。結果樣本水果：5個（其中價格的最大值為15，最小值為3）洗漱用品：10個（其中價格的最大值為98，最小值為1）電子裝置：3個（其中價格的最大值為8699，最小值為2300）其它：15個（其中價格的最大值為1000，最小值為80）

樣本1

將年齡為18歲的人按分數分組，並擷取人數最多的10個分數值以及每個分數的人數。

query = TermQuery('age', 18)
group_by = GroupByField('score', size = 10)

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=20, group_bys = [group_by]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for group_by in search_response.group_by_results:
    print("name:%s" % group_by.name)
    print("groups:")
    for item in group_by.items:
        print("key:%s, count:%d" % (item.key, item.row_count))

樣本2

將年齡為18歲的人按分數分組，並擷取人數最少的2個分數值以及每個分數的人數。

group_by = GroupByField('score', size = 2, group_by_sort = [RowCountSort(sort_order=SortOrder.ASC)])
search_response = client.search(table_name, index_name,
                                SearchQuery(TermQuery('age', 18), limit=100, get_total_count=True, group_bys = [group_by]),
                                ColumnsToGet(return_type=ColumnReturnType.ALL_FROM_INDEX))

for group_by in search_response.group_by_results:
    print("name:%s" % group_by.name)
    print("groups:")
    for item in group_by.items:
        print("key:%s, count:%d" % (item.key, item.row_count))

樣本3

將年齡為18歲的人按分數分組，並擷取人數最多的2個分數值、每個分數的人數以及按主鍵排序前三的人的資訊。

sort = RowCountSort(sort_order = SortOrder.DESC)
sub_agg = [TopRows(limit=3,sort=Sort([PrimaryKeySort(sort_order=SortOrder.DESC)]), name = 't1')]

group_by = GroupByField('l', size = 2, group_by_sort = [sort], sub_aggs = sub_agg)
search_response = client.search(table_name, index_name,
                                SearchQuery(TermQuery('age', 18), limit=100, get_total_count=True, group_bys = [group_by]),
                                ColumnsToGet(return_type=ColumnReturnType.ALL_FROM_INDEX))

for group_by in search_response.group_by_results:
    print("name:%s" % group_by.name)
    print("groups:")
    for item in group_by.items:
        print("\tkey:%s, count:%d" % (item.key, item.row_count))
        for sub_agg in item.sub_aggs:
            print("\t\tname:%s:" % sub_agg.name)
            for entry in sub_agg.value:
                print("\t\t\tvalue:%s" % str(entry))

樣本4

將年齡為18歲的人按分數和性別分組。

sort = RowCountSort(sort_order = SortOrder.ASC)
sub_group = GroupByField('sex', size = 10, group_by_sort = [sort])

group_by = GroupByField('score', size = 10, group_by_sort = [sort], sub_group_bys = [sub_group])
search_response = client.search(table_name, index_name,
                                SearchQuery(TermQuery('age', 18), limit=100, get_total_count=True, group_bys = [group_by]),
                                ColumnsToGet(return_type=ColumnReturnType.ALL_FROM_INDEX))

for group_by in search_response.group_by_results:
    print("name:%s" % group_by.name)
    print("groups:")
    for item in group_by.items:
        print("\tkey:%s, count:%d" % (item.key, item.row_count))
        for sub_group in item.sub_group_bys:
            print("\t\tname:%s:" % sub_group.name)
            for sub_item in sub_group.items:
                print("\t\t\tkey:%s, count:%s" % (str(sub_item.key), str(sub_item.row_count)))

範圍分組

根據一個欄位的範圍對查詢結果進行分組，欄位值在某範圍內放到同一分組內，返回每個範圍中相應的item個數。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Long和Double類型。
range[double_from, double_to)	分組的範圍。起始值double_from可以使用最小值Double.MIN_VALUE，結束值double_to可以使用最大值Double.MAX_VALUE。
sub_aggs和sub_group_bys	子統計彙總，子統計彙總會根據分組內容再進行一次統計彙總分析。例如按銷量分組後再按省份分組，即可獲得某個銷量範圍內哪個省比重比較大，實現方法是GroupByRange下添加一個GroupByField。

樣本

統計年齡為18歲的人中得分的分數在[80, 90)和[90, 100)兩個區間段的人數。

query = TermQuery('age', 18)
group_by = GroupByRange(field_name = 'score', ranges = [(80, 90),(90, 100)])

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=0, group_bys = [group_by]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for group_by in search_response.group_by_results:
    print("name:%s" % group_by.name)
    print("groups:")
    for item in group_by.items:
        print("range:%.1f~%.1f, count:%d" % (item.range_from, item.range_to, item.row_count))

地理位置分組

根據距離某一個中心點的範圍對查詢結果進行分組，距離差值在某範圍內放到同一分組內，返回每個範圍中相應的item個數。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Geo_point類型。
origin(double lat, double lon)	起始中心點的經緯度。 lat是起始中心點座標緯度，lon是起始中心點座標經度。
range[double_from, double_to)	分組的範圍，單位為米。起始值double_from可以使用最小值Double.MIN_VALUE，結束值double_to可以使用最大值Double.MAX_VALUE。
sub_aggs和sub_group_bys	子統計彙總，子統計彙總會根據分組內容再進行一次統計彙總分析。

樣本

統計年齡為18歲的人中家庭住址在距離學校一公裡以內和一公裡到兩公裡內的人數。其中學校經緯度為(31,116)。

query = TermQuery('age', 18)
group_by = GroupByGeoDistance(field_name = 'address', origin=GeoPoint(31, 116), ranges = [(0, 1000), (1000,2000)])

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=2, group_bys = [group_by]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for group_by in search_response.group_by_results:
    print("name:%s" % group_by.name)
    print("groups:")
    for item in group_by.items:
        print("range:%.1f~%.1f, count:%d" % (item.range_from, item.range_to, item.row_count))

過濾條件分組

按照過濾條件對查詢結果進行分組，擷取每個過濾條件匹配到的數量，返回結果的順序和添加過濾條件的順序一致。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
filter	過濾條件，返回結果的順序和添加過濾條件的順序一致。
sub_aggs和sub_group_bys	子統計彙總，子統計彙總會根據分組內容再進行一次統計彙總分析。

樣本

分別統計年齡為18歲的人中數學考了100分和語文考了100分的人數。

query = TermQuery('age', 18)
filter1 = TermQuery('math', 100)
filter2 = TermQuery('chinese', 100)
filters = [filter1, filter2]
group_by = GroupByFilter(filters)

search_response = client.search(
    table_name, index_name,
    SearchQuery(query, next_token = None, limit=2, group_bys = [group_by]),
    columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for group_by in search_response.group_by_results:
    print("name:%s" % group_by.name)
    print("groups:")
    i = 0
    for item in group_by.items:
        print("filter:%s=%s, count:%d" % (str(filters[i].field_name), str(filters[i].column_value), item.row_count))
        i=i+1

長條圖統計

按照指定資料間隔對查詢結果進行分組，欄位值在相同範圍內放到同一分組內，返回每個分組的值和該值對應的個數。

參數


參數	說明
name	自訂的統計彙總名稱，用於區分不同的統計彙總，可根據此名稱擷取本次統計彙總結果。
field	用於統計彙總的欄位，僅支援Long和Double類型。
interval	統計間隔。
field_range[min,max]	統計範圍，與interval參數配合使用限制分組的數量。`(fieldRange.max-fieldRange.min)/interval`的值不能超過2000。
min_doc_count	最小行數。當分組中的行數小於最小行數時，不會返回此分組的統計結果。
missing_value	當某行資料中的欄位為空白時，欄位值的預設值。如果未設定missing_value值，則在統計彙總時會忽略該行。如果設定了missing_value值，則使用missing_value值作為欄位值的預設值參與統計彙總。

樣本

query = TermQuery('product', '10010')
group_by = GroupByHistogram(field_name = 'latency', interval = 100, field_range = FieldRange(0, 10000), missing_value = 0)

search_response = client.search(table_name, index_name,
                                SearchQuery(query, next_token = None, limit=2, group_bys = [group_by]),
                                columns_to_get = ColumnsToGet(return_type = ColumnReturnType.ALL_FROM_INDEX))

for group_by in search_response.group_by_results:
    print("name:%s" % group_by.name)
    print("groups:")
    for item in group_by.items:
        print("%s:%s" % (item.key, item.value))