本頁面由 Cloud Translation API 翻譯而成。

在 BigQuery 中使用 Earth Engine 處理影像資料

本文將說明如何使用 ST_REGIONSTATS 函式結合光柵和向量資料，該函式會呼叫 Google Earth Engine，在 BigQuery 中執行地理空間分析。

總覽

光柵是像素的二維格線，每個像素都會指派一個或多個稱為頻帶的值。舉例來說，每個像素可能對應地球表面的某個平方公里，並有平均溫度和平均降雨量的頻帶。影像資料包括衛星圖像和其他連續的格線資料，例如天氣預報和土地覆蓋率。許多常見的圖片格式 (例如 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)
服務用量消費者 (roles/serviceusage.serviceUsageConsumer)
訂閱 BigQuery 共用中的資料集： 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 共用功能，您必須啟用 Analytics Hub API，並確保自己具備查看及訂閱項目的必要權限。

Google Earth Engine 會發布含有光柵資料的公開資料集。如要訂閱含有光柵資料的 Earth Engine 資料集，請按照下列步驟操作：

前往「分享 (Analytics Hub)」頁面。

前往「分享」(Analytics Hub)
按一下「搜尋商店資訊」。
在「Search for listings」欄位中輸入 "Google Earth Engine"。
按一下要訂閱的資料集。
按一下「訂閱」。
選用步驟：更新「專案」或「已連結的資料集名稱」欄位。
按一下 [儲存]。系統會將已連結的資料集新增至專案。

資料集包含一個資料表，有時稱為圖像資料表，可根據 STAC 項目規格，為一系列光柵圖片儲存中繼資料。圖片資料表類似於 Earth Engine 圖片集合 (ImageCollection)。

表格中的每一列都對應單一光柵圖像。每張圖片的光柵 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 函式支援以 GeoTIFF 格式儲存在 Cloud Storage 值區 (位於 US 或 us-central1 區域) 中的點陣資料。提供 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 篩選為單一圖片。使用 ee.Image.get('system:id') 方法，將該圖片的 IMAGE_PATH 值印到控制台。這個光柵 ID 為 'ee://IMAGE_PATH'。

像素權重

您可以為 ST_REGIONSTATS 函式中的 include 參數指定權重 (有時稱為遮罩值)，以決定計算中每個像素的權重。權重值必須介於 0 到 1 之間。超出這個範圍的權重會設為最接近的限制值 (0 或 1)。

如果像素的權重大於 0，就會視為有效。權重為 0 表示無效像素。無效像素通常代表缺少或不可靠的資料，例如被雲遮蔽的區域、感應器異常、處理錯誤，或是位於定義邊界外的地點。

如果您未指定權重，系統會根據落在幾何圖形內的像素比例，自動為每個像素加權，以便在區域統計資料中按比例納入。

如果部分重疊的像素具有從 include 引數到 ST_REGIONSTATS 的權重，則 BigQuery 會使用該權重與重疊區域的像素比率的最小值。

權重值的精確度與 FLOAT64 值不同。實際上，這些值的實際值與計算中使用的值最多可能相差 1/256 (約 0.4%)。

您可以在 include 引數中使用 Earth Engine 圖像運算式語法提供運算式，根據光柵頻帶內的特定條件動態加權像素。舉例來說，下列運算式會將計算限制在 probability 頻帶超過 70% 的像素：

include => 'probability > 0.7'

如果資料集包含權重因子頻帶，您可以使用下列語法：

include => 'weight_factor_band_name'

像素大小和分析規模

地理空間算繪影像是指與地球表面某些位置相對應的像素格線。影像的像素大小 (有時稱為縮放) 是指格狀座標參考系統中，像素一側的標稱大小。舉例來說，解析度為 10 公尺的光柵，其像素大小為 10 公尺 x 10 公尺。原始回報的像素大小可能會因資料集而異，從 1 公尺到 20 公里以上都有。

使用 ST_REGIONSTATS 函式計算區域統計資料時，您必須特別考量影像資料的像素大小。舉例來說，在國家/地區區域中匯總高解析度的影像資料可能會耗用大量運算資源，且不必要地精細。相反地，如果對區域 (例如城市地塊) 進行低解析度資料匯總，可能無法提供足夠的詳細資料。

為從分析中取得有意義且有效的結果，建議您選擇適合多邊形大小和分析目標的像素大小。您可以在 BigQuery 共用功能中，透過圖片資料表的說明部分查看每個光柵資料集的像素大小。

變更像素大小會影響與特定地理區域相交的像素數量，進而影響結果和解讀方式。我們不建議您為正式版分析變更像素大小。不過，如果您要製作查詢原型，增加像素大小可以縮短查詢執行時間和成本，尤其是高解析度資料。

如要變更像素大小，請將 options 引數中的 scale 設為 ST_REGIONSTATS 函式。舉例來說，如要計算超過 1,000 公尺像素的統計資料，請使用 options => JSON '{"scale":1000}'，這樣 Earth Engine 就會以要求的比例重新取樣圖像。如要進一步瞭解 Earth Engine 如何處理重新調整大小，請參閱 Google Earth Engine 說明文件中的「縮放」一節。

帳單

執行查詢時，由於 Earth Engine 會計算函式呼叫的結果，因此 ST_REGIONSTATS 函式的使用量會與其他查詢分開計費。無論您使用隨選結算或預留功能，我們都會依據 BigQuery 服務 SKU 下方的運算單元時數收取這項用量費用。如要查看向 Earth Engine 發出的 BigQuery 呼叫所產生的帳單金額，請查看帳單報表，並使用標籤篩選標籤鍵 goog-bq-feature-type，並設定值為 EARTH_ENGINE。

成本因素

執行 ST_REGIONSTATS 函式時，下列因素會影響計算用量：

輸入資料列數。
您使用的光柵圖像。部分光柵是從 Earth Engine 資料目錄中的來源圖像集合建立的複合圖，產生複合圖的運算資源各不相同。
圖片解析度。
輸入地理區域的大小和複雜度、與地理區域相交的像素數量，以及 Earth Engine 讀取的圖塊和位元組數量。
輸入地理位置在地球上的地點，相對於來源圖片、圖片的投影和解析度。
- 圖片投影可能會扭曲像素，尤其是高緯度或遠離圖片預期涵蓋範圍的像素。
- 對於組合算繪圖，與輸入地理區域相交的來源圖片數量可能會因地區和時間而異。舉例來說，某些衛星會根據其軌道和資料收集參數，在低緯度或高緯度產生更多圖像，或是根據變化的大氣條件省略圖像。
在 include 或 band_name 引數中使用公式，以及所涉及的頻帶數量。
先前結果的快取。

控管費用

如要控管與 ST_REGIONSTATS 函式相關的費用，您可以調整配額，控管函式可使用的時段時間量。預設值為每天 350 個時段小時。查看配額時，請將「指標」清單篩選為 earthengine.googleapis.com/bigquery_slot_usage_time，即可查看與 BigQuery 呼叫相關聯的 Earth Engine 配額。詳情請參閱 Google Earth Engine 說明文件，瞭解 BigQuery 迴紋函式配額。

限制

呼叫 ST_REGIONSTATS 函式的查詢必須在下列任一區域中執行：

US
us-central1
us-central2

後續步驟

請試試教學課程，瞭解如何使用影像資料分析溫度。
進一步瞭解 BigQuery 中的地理函式。
進一步瞭解如何使用地理空間資料。