このページの情報の一部またはすべては、S3NS の Trusted Cloud には適用されない場合があります。

BigQuery で Earth Engine を使用してラスターデータを操作する

このドキュメントでは、ST_REGIONSTATS 関数を使用してラスターデータとベクターデータを結合する方法について説明します。この関数は、Google Earth Engine を呼び出して BigQuery で地理空間分析を実行します。

概要

ラスターは、ピクセルの 2 次元グリッドです。各ピクセルには、バンドと呼ばれる 1 つ以上の値が割り当てられます。たとえば、各ピクセルが地球の表面の特定の 1 平方キロメートルに対応し、平均気温と平均降水量のバンドを持つことができます。ラスターデータには、衛星画像や、気象予報や土地被覆など、グリッドベースの連続データが含まれます。PNG ファイルや JPEG ファイルなど、一般的な画像形式の多くはラスターデータとしてフォーマットされています。

ラスターデータは、固定された長方形のグリッドではなく、線や曲線でデータが記述されるベクターデータと対比されることがよくあります。たとえば、BigQuery の GEOGRAPHY データ型を使用して、国、都市、その他の地域の境界を記述できます。

地理空間ラスターデータとベクトルデータは、多くの場合、ゾーン統計オペレーションを使用して結合されます。このオペレーションでは、特定のベクトル領域内のすべてのラスター値の集計値が計算されます。たとえば、次のような計算を行うことができます。

複数の都市の平均大気質。
建物のポリゴンのコレクションの太陽光発電ポテンシャル。
森林地帯の送電線沿いの火災リスクをまとめたもの。

BigQuery はベクターデータの処理に優れており、Google Earth Engine はラスターデータの処理に優れています。ST_REGIONSTATS 地理関数を使用すると、Earth Engine を使用してラスターデータを BigQuery に保存されているベクトルデータと組み合わせることができます。

ラスター値と計算されたゾーン統計情報を含む地球の地図。

始める前に

クエリで ST_REGIONSTATS 関数を使用するには、Earth Engine API を有効にします。

API の有効化
省略可: ST_REGIONSTATS 関数を使用して BigQuery Sharing（旧 Analytics Hub）に公開されたデータをサブスクライブして使用するには、Analytics Hub API を有効にします。

API の有効化

必要な権限

ST_REGIONSTATS 関数を呼び出すために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するように管理者へ依頼してください。

Earth Engine リソース閲覧者（roles/earthengine.viewer）
Service Usage ユーザー（roles/serviceusage.serviceUsageConsumer）
BigQuery Sharing でデータセットをサブスクライブする: BigQuery データ編集者（roles/bigquery.dataEditor）

ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

これらの事前定義ロールには、ST_REGIONSTATS 関数の呼び出しに必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

ST_REGIONSTATS 関数を呼び出すには、次の権限が必要です。

earthengine.computations.create
serviceusage.services.use
bigquery.datasets.create

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

ラスターデータを検索する

ST_REGIONSTATS 関数の raster_id パラメータは、ラスターデータのソースを指定する文字列です。以降のセクションでは、ラスター ID を見つけてフォーマットする方法について説明します。

BigQuery 画像テーブル

BigQuery Sharing（旧 Analytics Hub）を使用すると、BigQuery でラスターデータセットを検出してアクセスできます。BigQuery Sharing を使用するには、Analytics Hub API を有効にし、リスティングを表示してサブスクライブするための必要な権限があることを確認する必要があります。

Google Earth Engine は、ラスターデータを含む一般公開データセットを公開しています。ラスタデータを含む Earth Engine データセットをサブスクライブする手順は次のとおりです。

[共有（Analytics Hub）] ページに移動します。

[共有（Analytics Hub）] に移動
[リスティングを検索] をクリックします。
[リスティングを検索する] フィールドに「"Google Earth Engine"」と入力します。
登録するデータセットをクリックします。
[登録] をクリックします。
省略可: [プロジェクト] フィールドまたは [リンクデータセット名] フィールドを更新します。
[保存] をクリックします。リンクされたデータセットがプロジェクトに追加されます。

データセットには、STAC アイテム仕様に従って、ラスター画像のコレクションのメタデータを保存するテーブル（画像テーブルとも呼ばれます）が含まれています。画像テーブルは、Earth Engine の画像コレクション（ImageCollection）に似ています。

テーブルの各行は 1 つのラスター画像に対応しています。各画像のラスター ID は assets.image.href 列に保存されます。特定の画像を検索するには、properties 列の画像プロパティでフィルタします。バンドに関する情報は、テーブルの説明で確認できます。

たとえば、ERA5-Land データセットは、毎日の気候変数の統計情報を提供しており、一般公開されています。climate テーブルには複数のラスター ID が含まれています。次のクエリは、properties.start_datetime 列を使用して画像テーブルをフィルタして、2025 年 1 月 1 日に対応する画像のラスター ID を取得し、temperature_2m バンドを使用して国ごとの平均気温を計算します。

WITH SimplifiedCountries AS (
  SELECT
    ST_SIMPLIFY(geometry, 10000) AS simplified_geometry,
    names.primary AS name
  FROM
    `bigquery-public-data.overture_maps.division_area`
  WHERE
    subtype = 'country'
)
SELECT
  sc.simplified_geometry AS geometry,
  sc.name,
  ST_REGIONSTATS(
    sc.simplified_geometry,
    (SELECT assets.image.href
     FROM `LINKED_DATASET_NAME.climate`
     WHERE  properties.start_datetime = '2025-01-01 00:00:00'),
    'temperature_2m'
  ).mean - 273.15 AS mean_temperature
FROM
  SimplifiedCountries AS sc
ORDER BY
  mean_temperature DESC;

Cloud Storage GeoTIFF

GeoTIFF は、地理空間ラスターデータを保存するための一般的なファイル形式です。ST_REGIONSTATS 関数は、US または us-central1 リージョンにある Cloud Storage バケットに GeoTIFF 形式で保存されているラスターデータをサポートしています。Cloud Storage URI をラスタ ID として指定します（例: gs://bucket/folder/raster.tif）。

Earth Engine 画像アセット

ST_REGIONSTATS 関数は、raster_id 引数として Earth Engine 画像アセットのパスを渡すことをサポートしています。Earth Engine ラスターデータは、個々の画像または画像のコレクションとして使用できます。画像のラスター ID を確認する手順は次のとおりです。

Earth Engine データカタログで、目的のデータセットを検索します。
エントリの説明ページを開くには、データセット名をクリックします。Earth Engine スニペットは、単一の画像または画像のコレクションを表します。

Earth Engine スニペットの形式が ee.Image('IMAGE_PATH') の場合、ラスター ID は 'ee://IMAGE_PATH' です。

Earth Engine スニペットが ee.ImageCollection('IMAGE_COLLECTION_PATH') 形式の場合は、Earth Engine コードエディタを使用して ImageCollection を 1 つの画像にフィルタできます。ee.Image.get('system:id') メソッドを使用して、その画像の IMAGE_PATH 値をコンソールに出力します。ラスタ ID は 'ee://IMAGE_PATH' です。

ピクセルの重み

ST_REGIONSTATS 関数の include パラメータに重み（マスク値とも呼ばれる）を指定できます。この重みによって、計算で各ピクセルにどの程度の重みを付けるかが決まります。重み付けの値は 0～1 の範囲で指定する必要があります。この範囲外の重みは、最も近い値（0 または 1）に設定されます。

重みが 0 より大きいピクセルは有効と見なされます。重みが 0 の場合は、無効なピクセルであることを示します。無効なピクセルは通常、雲で覆われた領域、センサーの異常、処理エラー、定義された境界外の場所など、欠落しているデータや信頼性の低いデータを表します。

重みを指定しない場合、各ピクセルはジオメトリ内に収まるピクセルの割合で自動的に重み付けされ、ゾーン統計に比例して含まれるようになります。ジオメトリがピクセルのサイズの 1/256 未満の場合、ピクセルの重みは 0 になります。この場合、count と area は 0 になり、この 2 つを除くすべての統計値に対しては null が返されます。

部分的に重複するピクセルに include 引数から ST_REGIONSTATS までの重みが設定されている場合、BigQuery はその重みと、リージョンと重複するピクセルの割合の最小値を使用します。

重み値の精度は FLOAT64 値と同じではありません。実際には、真の値は計算で使用される値と最大で 1/256（約 0.4%）異なる可能性があります。

include 引数で Earth Engine の画像式構文を使用して式を指定すると、ラスターバンド内の特定の条件に基づいてピクセルを動的に重み付けできます。たとえば、次の式では、probability バンドが 70% を超えるピクセルにのみ計算を制限します。

include => 'probability > 0.7'

データセットに重み係数帯域が含まれている場合は、次の構文で使用できます。

include => 'weight_factor_band_name'

分析のピクセルサイズとスケール

地理空間ラスター画像は、地球の表面上の特定の位置に対応するピクセルのグリッドです。ラスターのピクセルサイズ（スケール）は、グリッドの座標参照システムにおけるピクセルの 1 エッジの公称サイズです。たとえば、解像度が 10 m のラスターでは、ピクセルのサイズは 10 m × 10 m です。元の報告されたピクセルサイズは、データセットによって 1 メートル未満から 20 キロメートル以上にまで大きく異なります。

ST_REGIONSTATS 関数を使用してゾーン統計を計算する場合、ラスターデータのピクセルサイズは重要な考慮事項です。たとえば、国の地域で高解像度のラスターデータを集計すると、計算負荷が高くなり、粒度が不必要に細かくなることがあります。逆に、都市区画などの低解像度データを地域全体で集計すると、十分な詳細が得られない可能性があります。

分析から有意義で効率的な結果を得るには、ポリゴンのサイズと分析の目的に適したピクセルサイズを選択することをおすすめします。各ラスターデータセットのピクセルサイズは、BigQuery Sharing の画像テーブルの説明セクションで確認できます。

ピクセルサイズを変更すると、特定の地域と交差するピクセル数が変わり、結果とその解釈に影響します。本番環境の分析でピクセルサイズを変更することはおすすめしません。ただし、クエリのプロトタイピングを行う場合は、ピクセルサイズを大きくすると、特に高解像度データの場合に、クエリの実行時間と費用を削減できます。

ピクセルサイズを変更するには、options 引数の scale を ST_REGIONSTATS 関数に設定します。たとえば、1,000 メートルのピクセルで統計情報を計算するには、options => JSON '{"scale":1000}' を使用します。これにより、Earth Engine はリクエストされたスケールで画像をリサンプリングします。Earth Engine でのリスケーリングの処理方法の詳細については、Google Earth Engine ドキュメントのスケールをご覧ください。

ラスタのピクセルよりも大幅に小さいポリゴンの統計情報を計算すると、不正確な結果や null の結果が生成されることがあります。このような場合は、ST_CENTROID を使用して、ポリゴンをその重心点に置き換える方法があります。

課金

クエリを実行すると、Earth Engine は関数呼び出しの結果を計算するため、ST_REGIONSTATS 関数の使用量はクエリの残りの部分とは別に課金されます。この使用量は、オンデマンド課金または予約を使用しているかどうかにかかわらず、BigQuery Services SKU のスロット時間単位で課金されます。Earth Engine への BigQuery 呼び出しに対して請求された金額を確認するには、請求レポートを表示し、ラベルを使用して、ラベルキー goog-bq-feature-type、値 EARTH_ENGINE でフィルタします。ST_REGIONSTATS 関数が失敗した場合、使用された Earth Engine 計算に対して料金は請求されません。

コスト要因

ST_REGIONSTATS 関数を実行する際のコンピューティング使用量には、次の要因が影響します。

入力行数。
使用するラスター画像。一部のラスターは、Earth Engine データカタログのソース画像コレクションから作成されたコンポジットであり、コンポジット結果を生成するためのコンピューティングリソースは異なります。
画像の解像度。
入力ジオグラフィのサイズと複雑さ、ジオグラフィと交差するピクセルの数、Earth Engine が読み取る画像タイルとバイト数。
ソース画像、画像の投影、解像度を基準とした、地球上の入力地理情報の位置。
- 画像投影では、特に高緯度や画像の対象範囲の外側にあるピクセルが歪むことがあります。
- 複合ラスターの場合、入力地域と交差するソース画像の数は、地域や時間によって異なる場合があります。たとえば、一部の衛星は、軌道やデータ収集パラメータに応じて、低緯度または高緯度でより多くの画像を生成することや、大気条件の変化に応じて画像を省略することがあります。
include 引数または band_name 引数での数式の使用と、それらに関連するバンドの数。
以前の結果のキャッシュ保存。

費用を管理する

ST_REGIONSTATS 関数に関連する費用を制御するには、関数で使用できるスロット時間の量を制御する割り当てを調整します。デフォルトは 1 日あたり 350 スロット時間です。割り当てを表示するときに、指標リストを earthengine.googleapis.com/bigquery_slot_usage_time にフィルタすると、BigQuery からの呼び出しに関連付けられた Earth Engine の割り当てが表示されます。詳細については、Google Earth Engine のドキュメントで BigQuery ラスター関数の割り当てをご覧ください。

制限事項

ST_REGIONSTATS 関数を呼び出すクエリは、次のいずれかのリージョンで実行する必要があります。

US
us-central1
us-central2

次のステップ

ラスターデータを使用して温度を分析する方法に関するチュートリアルを試す。
BigQuery の地理関数の詳細を確認する。
地理空間データの操作の詳細を確認する。