本頁說明如何使用 ee.FeatureCollection.loadBigQueryTable() 和 ee.FeatureCollection.runBigQuery() 方法，將 BigQuery 資料表整合至 Earth Engine 工作流程，做為 ee.FeatureCollection 物件。
從 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 費用。您可以在使用中的專案的 Google Cloud API 資訊主頁中查看相應的 BigQuery 用量 (請參閱「監控 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 功能：
- 工作記錄：存取專案過去六個月的查詢執行記錄 (詳情請參閱「列出工作」)。
- 查詢快取：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.createbigquery.jobs.create
如需管理權限的詳細資訊，請參閱 BigQuery 存取權控管說明文件。
資料篩選
每個 ee.FeatureCollection 都可以使用 .filter(Filter) 方法進行篩選。為讓 Google Earth Engine 使用者享有高度平行化的 BigQuery 表格資料處理功能，我們會將 Earth Engine 篩選器轉換為 BigQuery 可解讀的語言，並連同讀取資料表要求一併傳送。這個方法確實會將篩選器處理作業移至 BigQuery 堆疊，但也會受到兩項限制：
與 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()。
部分較複雜的 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。詳情請參閱「資料篩選」一節。
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')
如果 BigQuery 資料表含有自動產生的 ID，則在
system:index上進行聯結可能會導致非預期行為。為避免發生這種情況，請考慮手動將system:index新增至 BigQuery 資料表，或在其他資源上聯結資料表。如要進一步瞭解索引，請參閱資料索引部分。ee.FeatureCollection.randomColumn()方法不適用於 BigQuery 自動產生的 ID。建議您使用ee.FeatureCollection.randomColumn()方法中的rowKeys參數，指定替代金鑰。您也可以手動將random或system:index資料欄新增至 BigQuery 來源資料表。如要進一步瞭解索引，請參閱資料索引部分。