BigQuery から読み取る

このページでは、ee.FeatureCollection.loadBigQueryTable() メソッドと ee.FeatureCollection.runBigQuery() メソッドを使用して、BigQuery テーブルを ee.FeatureCollection オブジェクトとして Earth Engine ワークフローに統合する方法について説明します。

BigQuery からデータを読み込む

ee.FeatureCollection.loadBigQueryTable() 関数は、BigQuery テーブルを ee.FeatureCollection オブジェクトにシームレスに読み取ります。指定されたテーブルに接続し、すべてのデータ型を変換して、必要なフィルタとセレクタを適用し、必要に応じてコレクションにインデックスを追加します。この関数は Earth Engine のインタラクティブ環境を使用し、結果をクライアントに直接返して、表示したり、より大規模な分析のコンポーネントとして使用したりできるようにします。

JavaScript

// Load the BigQuery table with a specified geometry column.
var features = ee.FeatureCollection.loadBigQueryTable({
  table: 'my_project.my_dataset.my_table',
  geometryColumn: 'geo'
});

// Display features on the map.
Map.addLayer(features);

Python

# Load the BigQuery table with a specified geometry column.
features = ee.FeatureCollection.loadBigQueryTable(
    table='my_project.my_dataset.my_table',
    geometryColumn='geo')

# Display the first feature.
display(features.first().getInfo())

課金

リクエストの処理中に使用された EECU 時間の費用は、他の Earth Engine メソッドと同様に呼び出し元に請求されます（EECU の概要をご覧ください）。

Earth Engine へのデータの転送に関連して、BigQuery の追加費用は発生しません。対応する BigQuery の使用量は、使用されたプロジェクトの Google Cloud API ダッシュボード（API 使用量のモニタリングを参照）に表示されますが、この方法で BigQuery データを読み取っても費用は発生しません。

BigQuery からデータをクエリする

ee.FeatureCollection.runBigQuery() メソッドは BigQuery SQL クエリを実行し、結果を ee.FeatureCollection オブジェクトとして返します（クエリの詳細については、クエリの実行に関するドキュメントをご覧ください）。

JavaScript

// Construct a BigQuery query.
var query = 'SELECT * FROM my_project.my_dataset.my_table WHERE column > 1000';

// Run the query and return the results as a FeatureCollection.
var features = ee.FeatureCollection.runBigQuery(query);

// Print the first feature.
print(features.first());

Python

# Construct a BigQuery query.
query = 'SELECT * FROM my_project.my_dataset.my_table WHERE column > 1000'

# Run the query and retrieve the results as a FeatureCollection.
features = ee.FeatureCollection.runBigQuery(query)

# Print the first feature.
print(features.first().getInfo())

BigQuery のクエリ

ee.FeatureCollection.runBigQuery() の各呼び出しは、個別の BigQuery クエリジョブを開始します（クエリの詳細については、クエリの実行に関するドキュメントをご覧ください）。これにより、次の BigQuery の主な機能を使用できます。

  • ジョブ履歴: プロジェクトのクエリ実行の 6 か月間の履歴にアクセスします（詳細については、ジョブを一覧表示するをご覧ください）。
  • クエリ キャッシュ保存: BigQuery は、可能な限りクエリ結果を自動的にキャッシュ保存します。後続の同一のクエリはキャッシュからデータを取得するため、冗長な料金が発生しません（詳細については、キャッシュに保存されているクエリ結果を使用するをご覧ください）。

クエリまたは BigQuery での使用方法については、BigQuery のドキュメントをご覧ください。

課金

リクエストの処理中に使用された EECU の費用は、他の Earth Engine メソッドと同様に呼び出し元に請求されます（EECU の概要をご覧ください）。また、BigQuery の課金モデルに従って、クエリの実行に対して呼び出し元に課金されます。

Earth Engine へのデータの転送に関連して、BigQuery の追加費用は発生しません。対応する BigQuery の使用量は、使用されたプロジェクトの Google Cloud API ダッシュボード（API 使用量のモニタリングを参照）に表示されますが、この方法で BigQuery データを読み取っても費用は発生しません。

ee.FeatureCollection.runBigQuery() に関連する潜在的な費用を制御するために、maxBytesBilled パラメータはセーフガードとして機能します。この上限を超える BigQuery ジョブは失敗し、課金されません。maxBytesBilled のデフォルト値は 100 GB です。この上限を超えて呼び出しがブロックされた場合は、スクリプトで別の値を指定できます。

前提条件と権限

この機能を使用するには、呼び出し元の Cloud プロジェクトで BigQuery API と BigQuery Storage API が有効になっている必要があります。[API を有効にする] ページの手順に沿って、適切な API を有効にします。

標準の Earth Engine のロールと権限に加えて、参照される BigQuery テーブルに対する読み取りアクセス権と、ターゲット プロジェクトで読み取りセッションとジョブを作成する権限が必要です。必要な BigQuery 固有の権限は次のとおりです。

  • bigquery.tables.get（アクセスされたテーブルに対するもの）
  • bigquery.tables.getData（アクセスされたテーブルに対するもの）
  • bigquery.readSession.create
  • bigquery.jobs.create

権限の管理の詳細については、BigQuery アクセス制御のドキュメントをご覧ください。

データのフィルタリング

すべての ee.FeatureCollection は、.filter(Filter) メソッドを使用してフィルタできます。Google Earth Engine ユーザーが高度に並列化された BigQuery 表形式データ処理を利用できるように、Earth Engine フィルタを BigQuery が理解できる言語に変換し、読み取りテーブル リクエストとともに送信します。このアプローチでは、フィルタ処理が BigQuery スタックに移動しますが、次の 2 つの制限もあります。

  1. BigQuery の他のすべてのクエリと同様に（BigQuery の割り当てを参照）、このリクエストのサイズは 10 MB に制限されています。つまり、渡されるフィルタは複雑になりすぎないようにする必要があります。10 MB の上限に達すると、次のエラーが発生します。

    Filter sent to BigQuery is too long. This error may be caused by too complicated geometry in geometry filters. Consider simplifying the filter and used values.

    このエラーの一般的な原因は、頂点の多いジオメトリでフィルタリングすることです。この問題を解決するには、問題のあるオブジェクトで ee.Geometry.simplify() の使用を検討してください。

  2. 複雑な Earth Engine フィルタの一部は、BigQuery の同等のフィルタに変換できません。たとえば、BigQuery は ARRAY の等価性チェックをサポートしていません。このような場合、フィルタは変換されず、データの読み取り後に Earth Engine で適用されます。

データのインデックス作成

Earth Engine コレクションは内部インデックス処理に依存しますが、BigQuery ではテーブルのインデックス処理を維持することは推奨されていません。これら 2 つのシステムを連携させるには、次のようにコレクション インデックスを作成します。

  • BigQuery テーブルに system:index という名前の列が含まれている場合は、FeatureCollection のインデックス作成に使用します。

    このような場合、インデックスが一意であることを確認するのは呼び出し元の責任です。そうしないと、コレクションが予期しない動作をする可能性があります。特徴インデックスは空でない文字列である必要があります。そのため、system:index 列に文字列以外の値または null 値を使用して BigQuery テーブルを読み込むと失敗します。

  • BigQuery テーブルに system:index 列が含まれていない場合は、自動的に生成されます。

    2 つの読み取りリクエスト間のインデックスは安定していますが、リクエストがまったく同じで、フィルタが考慮されている場合に限ります。そうしないと、インデックスが同じ特徴に対応していることを保証できません。したがって、呼び出し元にとって正確に一意のデータ インデックス作成が重要な場合は、BigQuery に system:index 列を手動で追加することをおすすめします。

制限事項

  • ee.FeatureCollection.loadBigQueryTable() 呼び出しで参照されるテーブルの選択されたすべての列のサイズは 400 GB に制限されます。この上限に達すると、次のエラーが発生します。

    Failed to read table from BigQuery: Requested data size is too large to read. Consider using selectors to specify only required columns.

    このような場合は、必要な列のみを読み取るようにセレクタを制限するか、ee.FeatureCollection.runBigQuery() を使用して BigQuery でテーブルを前処理し、取得するデータ量を減らすことを検討してください。

  • ee.FeatureCollection.runBigQuery() メソッドでは、クエリ結果のサイズに 10 GB の上限が適用されます。ソーステーブルのサイズは任意ですが、データ量が多いほどクエリ費用が増加します。

  • 変換後のフィルタのサイズは 10 MB に制限されます。詳細については、データ フィルタリングのセクションをご覧ください。

  • Earth Engine アプリでは、ee.FeatureCollection.loadBigQueryTable() または ee.FeatureCollection.runBigQuery() を使用できません。

注意点

  • ee.FeatureCollection.loadBigQueryTable() は、リンクされたデータセットのリソースをサポートしていません。このようなテーブルからデータを読み込もうとすると、「テーブルが見つかりません」というエラーが発生します。

    回避策として、リンクされたデータセットからリクエストされたテーブルを指定するクエリで ee.FeatureCollection.runBigQuery() を実行することを検討してください。次に例を示します。

    JavaScript

    var features = ee.FeatureCollection.runBigQuery({
  query: 'SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn: 'geo'
});

    Python

    features = ee.FeatureCollection.runBigQuery(
  query='SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn='geo')

  • 自動生成された ID を含む BigQuery テーブルで system:index を結合すると、予期しない動作が発生する可能性があります。これを回避するには、BigQuery テーブルに system:index を手動で追加するか、別のプロパティでテーブルを結合することを検討してください。インデックス登録の詳細については、データのインデックス登録セクションをご覧ください。

  • ee.FeatureCollection.randomColumn() メソッドは、BigQuery の自動生成 ID では機能しません。ee.FeatureCollection.randomColumn() メソッドの rowKeys パラメータを使用して、代替キーを指定することを検討してください。BigQuery ソーステーブルに random 列または system:index 列を手動で追加することもできます。インデックス登録の詳細については、データのインデックス登録セクションをご覧ください。