geo クエリ - Tablestore SDK for Python - Tablestore - Alibaba Cloud ドキュメントセンター

Tablestore SDK for Python を使用して、中心点からの距離、バウンディングボックス、またはポリゴンによってデータをフィルターします。

前提条件

Tablestore SDK for Python をインストールし、クライアントを初期化してください。

説明

geo クエリは、GeoPoint フィールド内の地理的位置に基づいてデータをフィルターします。距離、バウンディングボックス、またはポリゴンでクエリを実行できます。search メソッドを呼び出すとき、必要な地理的範囲に基づいてクエリタイプを GeoDistanceQuery、GeoBoundingBoxQuery、または GeoPolygonQuery に設定します。

GeoDistanceQuery(field_name, center_point, distance)
GeoBoundingBoxQuery(field_name, top_left, bottom_right)
GeoPolygonQuery(field_name, points)

次の例では、location フィールドが 30.25,120.16 から 200,000 メートル以内にある行をクエリし、最大 10 行と一致する行の総数を返します。

query = GeoDistanceQuery("location", "30.25,120.16", 200000)
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)

パラメーター

検索リクエスト

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`	クエリ条件。クエリオブジェクト (`GeoDistanceQuery`、`GeoBoundingBoxQuery`、または `GeoPolygonQuery` のいずれか) を設定します。
sort (任意)	`Sort`	クエリ結果のソート順。詳細については、「結果のソートとページ分割」をご参照ください。
get_total_count (任意)	`bool`	一致する行の総数を返すかどうかを指定します。デフォルト値：`False`。このパラメーターを `True` に設定すると、クエリのオーバーヘッドが増加します。
next_token (任意)	`bytes`	ページネーショントークン。次のページを取得するには、このパラメーターを前のレスポンスの `next_token` に設定します。詳細については、「結果のソートとページ分割」をご参照ください。
offset (任意)	`int`	現在のクエリが開始するオフセット。このパラメーターを浅いページネーションに使用します。
limit (任意)	`int`	返す行の最大数。このパラメーターが `0` に設定されている場合、行データは返されません。
aggs (任意)	`list[Agg]`	集計設定。詳細については、「集計」をご参照ください。
group_bys (任意)	`list[BaseGroupBy]`	グループ化設定。詳細については、「集計」をご参照ください。
collapse_field (任意)	`Collapse`	指定されたフィールドに基づいて重複する結果を削除する、結果の折りたたみ設定。詳細については、「クエリ結果の折りたたみ」をご参照ください。

3 つすべてのクエリタイプで、座標は 緯度,経度 形式を使用します。緯度、経度の順で記述します。緯度の範囲は [-90,+90] で、経度の範囲は [-180,+180] です。例：35.8,-45.91。

地理距離条件

search_query.query は GeoDistanceQuery 型で、次のパラメーターが含まれます。

名前	型	説明
field_name (必須)	`str`	クエリ対象の `GeoPoint` フィールドの名前。
center_point (必須)	`str`	中心点の座標。
distance (必須)	`float`	中心点からの最大距離。単位：メートル。

地理バウンディングボックス条件

search_query.query は GeoBoundingBoxQuery 型で、次のパラメーターが含まれます。

名前	型	説明
field_name (必須)	`str`	クエリ対象の `GeoPoint` フィールドの名前。
top_left (必須)	`str`	左上隅の座標。
bottom_right (必須)	`str`	右下隅の座標。

地理ポリゴン条件

search_query.query は GeoPolygonQuery 型で、次のパラメーターが含まれます。

名前	型	説明
field_name (必須)	`str`	クエリ対象の `GeoPoint` フィールドの名前。
points (必須)	`list[str]`	ポリゴンを形成する座標のリスト。境界の順に座標を指定します。

返される列

columns_to_get は ColumnsToGet 型で、次のパラメーターが含まれます。

名前	型	説明
column_names (任意)	`list[str]`	返す属性列の名前。このパラメーターは、`return_type` が `SPECIFIED` の場合にのみ指定します。
return_type (任意)	`ColumnReturnType`	返される列のモード。`NONE` (デフォルト) はプライマリキー列のみを返します。`SPECIFIED` は `column_names` 内の属性列を返します。`ALL` はテーブルからすべての属性列を返します。`ALL_FROM_INDEX` はインデックス付きのすべての属性列を返します。

レスポンス

search メソッドは SearchResponse を返します。次の表に、主要なフィールドを示します。

フィールド	型	説明
rows	`list[Row]`	現在のクエリによって返された行。行数は `limit` を超えません。
next_token	`bytes`	次のページのトークン。このフィールドが空でない場合は、次のリクエストに渡して読み込みを続行します。
total_count	`int`	一致する行の数。値は `get_total_count` の設定によって決まります。
is_all_succeed	`bool`	すべてのインデックスパーティションがクエリされたかどうかを示します。値が `False` の場合、部分的な結果が返され、`total_count` が実際の一致する行数より少なくなる可能性があります。
agg_results	`list[AggResult]`	集計結果。`aggs` が設定されていない場合、このフィールドは空になります。
group_by_results	`list[GroupByResult]`	グループ化の結果。`group_bys` が設定されていない場合、このフィールドは空になります。
search_hits	`list[SearchHit]`	関連性スコア、ハイライト、一致する子行などの拡張情報を含む検索ヒット。

タプル互換のレスポンス

Tablestore SDK for Python 5.2.0 以降では、検索 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()

例

バウンディングボックス内のデータのクエリ

次の例では、左上隅 32.0,119.0 と右下隅 29.0,122.0 で定義されるバウンディングボックス内のデータをクエリします。

query = GeoBoundingBoxQuery(
    "location",
    "32.0,119.0",
    "29.0,122.0",
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)

ポリゴン内のデータのクエリ

次の例では、4 つの座標で形成されるポリゴン内のデータをクエリします。

query = GeoPolygonQuery(
    "location",
    [
        "29.0,119.0",
        "32.0,119.0",
        "32.0,122.0",
        "29.0,122.0",
    ],
)
response = client.search(
    "example_table",
    "example_index",
    SearchQuery(query, limit=10),
    ColumnsToGet(return_type=ColumnReturnType.ALL),
)
print(response.rows)