BigQuery から読み取る

注: ee.FeatureCollection.loadBigQueryTable() 関数と ee.FeatureCollection.runBigQuery() 関数はプレビュー版です。サポートをリクエストする場合、またはフィードバックを提供する場合は、[e-mail] までメールをお送りください。

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

BigQuery からデータを読み込む

プレビュー: ee.FeatureCollection.loadBigQueryTable() 関数はプレビュー版であり、変更される可能性があります。

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() 関数はプレビュー版であり、変更される可能性があります。

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 に結合すると、予期しない動作が発生する可能性があります。この問題を回避するには、system:index を手動で BigQuery テーブルに追加するか、別のプロパティでテーブルを結合することを検討してください。インデックス登録の詳細については、データのインデックス登録をご覧ください。

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