集約 - Tablestore SDK for Python - Tablestore - Alibaba Cloud ドキュメントセンター

Tablestore Python SDK を使用して、多次元インデックスの結果でメトリクスの集計とグルーピングを実行します。

前提条件

Tablestore Python SDK をインストールし、クライアントを初期化します。

集約機能には SDK バージョン 5.2.1 以降が必要です。最新の SDK バージョンの使用を推奨します。

説明

集計では、検索インデックスのクエリ結果からメトリクスを計算したり、グループを作成したりします。メトリクス集計オブジェクトを SearchQuery.aggs に、グルーピングオブジェクトを SearchQuery.group_bys に追加します。リクエスト内の各 name は一意である必要があり、対応するレスポンス結果を識別します。集計結果のみを取得するには、limit を 0 に設定します。

機能	説明
Min、Max、Sum、Avg	最小値、最大値、合計、平均を計算します。
Count、個別カウント	`Count` は、空でないフィールド値を持つ行をカウントします。`DistinctCount` は、個別のフィールド値をカウントします。
パーセンタイル	1 つ以上のパーセンタイルを計算します。
TopRows	各グループ内で上位にソートされた行をサブアグリゲーションとして返します。
GroupByField、GroupByComposite	1 つのフィールド値またはフィールドの組み合わせでグループ化します。
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 (required)	`Query`	集計範囲を決定するクエリ条件。すべての行を集計するには、`MatchAllQuery` を使用します。
aggs (optional)	`list[Agg]`	メトリック集計のリスト。名前が異なる集計を組み合わせることができます。
group_bys (optional)	`list[BaseGroupBy]`	グルーピングのリスト。名前が異なるグルーピングを組み合わせることができます。
limit (optional)	`int`	返すクエリ行の数。このパラメーターを `0` に設定すると、集計結果のみを取得します。

メトリック集計

次のオブジェクトを search_query.aggs に追加します。 field は集計フィールド、 name は結果を識別し、 missing_value はフィールドが欠損している場合に使用します。 missing_value が指定されていない場合、そのフィールドを持たない行は無視されます。

最小値、最大値、平均値

名前	タイプ	説明
field (必須)	`str`	集計フィールド。サポートされるタイプ： `Long`、 `Double`、 `Date`。
missing_value (任意)	`str / int / float`	フィールドが欠損している場合に使用する値。
name (任意)	`str`	集計名。デフォルト値：それぞれ `min`、 `max`、 `avg`。

合計

名前	タイプ	説明
field (必須)	`str`	集計フィールド。サポートされるタイプ： `Long`、 `Double`。
missing_value (任意)	`int / float`	フィールドが欠損している場合に合計に使用する値。
name (任意)	`str`	集計名。デフォルト値： `sum`。

カウント

名前	タイプ	説明
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`。

パーセンタイル

名前	タイプ	説明
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]`	複数フィールドグルーピングのソース。 `GroupByField`、`GroupByHistogram`、または `GroupByDateHistogram` タイプのソースを最大 32 個まで指定できます。
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 (optional)	`int / float`	The value used in the histogram when the field is missing.
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 グリッドの精度。enum の数値が大きいほど、グリッドは小さくなります。
size (optional)	`int`	The number of grid groups to return.
sub_aggs (任意)	`list[Agg]`	メトリックのサブ集約。
sub_group_bys (任意)	`list[BaseGroupBy]`	サブグルーピング。
name (任意)	`str`	グルーピング名。デフォルト値: `group_by_geo_grid`。

説明

GroupByComposite は Tablestore 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 を持ち、その items フィールドに各グループのグループキー、行数、サブ集計、およびサブグルーピングの結果が格納されます。GroupByComposite の結果には、続きを読み取るために source_group_by_names と next_token も含まれます。各グループの keys は、sources に対応する文字列リストです。欠損しているフィールドの値は None で表されます。

タプル互換のレスポンス

Tablestore SDK for Python 5.2.0 以降では、search API はタプルの代わりにレスポンスオブジェクトを返します。バージョン 5.1.0 以前では、タプルが直接返されます。バージョン 5.2.1 以降では、SearchResponse.v1_response() を呼び出して、以前のバージョンと互換性のあるタプルを取得できます。新しいコードでは、レスポンスフィールドが拡張された場合のアンパックエラーを避けるために、SearchResponse の属性に直接アクセスしてください。

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

例

複数フィールドグループのページ分割

次の例では、category と price でグループ化し、1 ページあたり 2 つのグループを返します。

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)