讀取 BigQuery

本頁面說明如何使用 ee.FeatureCollection.loadBigQueryTable() 和 ee.FeatureCollection.runBigQuery() 方法，將 BigQuery 資料表整合至 Earth Engine 工作流程，並以 ee.FeatureCollection 物件呈現。

從 BigQuery 載入資料

ee.FeatureCollection.loadBigQueryTable() 函式可順暢地將 BigQuery 資料表讀取至 ee.FeatureCollection 物件。它會連線至指定的資料表、轉換所有資料類型、套用必要的篩選器和選取器，並視需要為集合新增索引。這個函式會使用 Earth Engine 的互動環境，直接將結果傳回給用戶端，供其查看或用於更大規模分析的元件。

JavaScriptPython
// 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);
      
# 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 費用。您可以在使用專案的 Google Cloud API 資訊主頁中查看對應的 BigQuery 用量 (請參閱「監控 API 用量」)，但以這種方式讀取 BigQuery 資料不會產生費用。

查詢 BigQuery 中的資料

ee.FeatureCollection.runBigQuery() 方法會執行 BigQuery SQL 查詢，並將結果以 ee.FeatureCollection 物件形式傳回 (如要進一步瞭解查詢，請參閱「執行查詢」)。

JavaScriptPython
// 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());
      
# 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 的主要功能：

  • 工作記錄：查看專案查詢執行作業的六個月記錄 (詳情請參閱「列出工作」)。
  • 查詢快取：BigQuery 會盡可能自動快取查詢結果。後續相同的查詢會從快取中擷取資料，避免重複收費 (詳情請參閱「使用快取查詢結果」)

如要瞭解查詢或如何在 BigQuery 中使用查詢，請參閱 BigQuery 說明文件。

帳單

在處理要求期間使用的 EECU 費用會向呼叫端收費，就像任何其他 Earth Engine 方法一樣 (請參閱「EECU 總覽」)。此外，系統會根據 BigQuery 帳單計費模式，向呼叫端收取執行查詢的費用。

將資料移轉至 Earth Engine 不會產生額外的 BigQuery 費用。您可以在使用專案的 Google Cloud API 資訊主頁中查看對應的 BigQuery 用量 (請參閱「監控 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 存取權控管說明文件。

資料篩選

您可以使用 .filter(Filter) 方法篩選每個 ee.FeatureCollection。為了讓 Google Earth Engine 使用者能享有 BigQuery 表格式資料處理功能的高度平行處理效益，我們將 Earth Engine 篩選器轉譯成 BigQuery 可理解的語言，並與讀取資料表要求一起傳送。這種做法確實會將篩選器處理作業移至 BigQuery 堆疊，但也受到兩項限制：

  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 則不建議保留索引資料表。為了讓這兩個系統能搭配運作，我們會以以下方式建立收藏品索引：

  • 如果 BigQuery 表格包含名為 system:index 的資料欄，我們會使用該欄為 FeatureCollection 建立索引。

    在這種情況下，呼叫端必須確保索引是唯一的。否則，集合可能會發生非預期的異常行為。特徵索引必須是非空字串，因此如果 system:index 資料欄的值不是字串或 null，則無法載入 BigQuery 資料表。

  • 如果 BigQuery 資料表不含 system:index 欄，系統會自動產生該欄。

    兩個讀取要求之間的索引是穩定的，但只有在考量篩選器的情況下，要求才能完全相同。否則我們無法依據索引對應相同的功能。因此，如果對呼叫端來說，精確的唯一資料索引很重要，建議您手動在 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。詳情請參閱「資料篩選」一節。

注意事項

  • ee.FeatureCollection.loadBigQueryTable() 不支援已連結資料集中的資源。嘗試從這類資料表載入資料時，會導致「找不到資料表」錯誤。

    解決方法是考慮使用查詢執行 ee.FeatureCollection.runBigQuery()，指定連結資料集中的所需資料表。例如：

    JavaScriptPython
    var features = ee.FeatureCollection.runBigQuery({
  query: 'SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn: 'geo'
});
      
    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 參數指定替代索引鍵。您也可以手動將 random 或 system:index 欄新增至 BigQuery 來源資料表。如要進一步瞭解索引，請參閱「資料索引」一節。