在 BigQuery 中使用 Earth Engine 处理光栅数据

本文档介绍了如何使用 ST_REGIONSTATS 函数来合并光栅数据和矢量数据，该函数使用 Google Earth Engine 来访问 BigQuery 中的图片和光栅数据。

概览

栅格是一个二维像素网格，每个像素都被分配了一个或多个称为“波段”的值。例如，每个像素可以对应于地球表面上的一个特定平方公里，并具有平均温度和平均降雨量的波段。光栅数据包括卫星图像和其他基于网格的连续数据，例如天气预报和土地覆盖数据。许多常见的图片格式（例如 PNG 或 JPEG 文件）都采用光栅数据格式。

栅格数据通常与矢量数据形成对比，矢量数据通过线条或曲线而非固定的矩形网格来描述数据。例如，您可以使用 BigQuery 中的 GEOGRAPHY 数据类型来描述国家/地区、城市或其他区域的边界。

地理空间光栅数据和矢量数据通常通过区域统计信息操作进行组合，该操作可计算给定矢量区域内所有光栅值的汇总。例如，您可能需要计算以下内容：

• 一组城市的平均空气质量。
• 一组建筑物多边形的太阳能发电潜力。
• 森林地区输电线路走廊沿线的火灾风险摘要。

BigQuery 擅长处理矢量数据，而 Google Earth Engine 擅长处理栅格数据。您可以使用 ST_REGIONSTATS 地理位置函数将使用 Earth Engine 的光栅数据与存储在 BigQuery 中的向量数据相结合。

准备工作

1. 如需在查询中使用 ST_REGIONSTATS 函数，请启用 Earth Engine API。

   启用该 API

2. 可选：如需使用 ST_REGIONSTATS 函数订阅并使用发布到 BigQuery Sharing（以前称为 Analytics Hub）的数据，请启用 Analytics Hub API。

   启用该 API

所需权限

如需获得调用 ST_REGIONSTATS 函数所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

• Earth Engine Resource Viewer (roles/earthengine.viewer)
• Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• 订阅 BigQuery Sharing中的数据集： BigQuery Data Editor (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 sharing，您需要启用 Analytics Hub API，并确保您拥有查看和订阅产品详情所需的权限。

Google Earth Engine 会发布公开可用的数据集，其中包含 US 和 EU 多区域中的光栅数据。如需订阅包含栅格数据的 Earth Engine 数据集，请按以下步骤操作：

1. 前往 Sharing (Analytics Hub) 页面。

   前往 Sharing (Analytics Hub)

2. 点击 搜索列表。

3. 在搜索列表字段中，输入 "Google Earth Engine"。

4. 点击要订阅的数据集。

5. 点击订阅。

6. 可选：更新项目或关联数据集名称字段。

7. 点击保存。关联的数据集已添加到您的项目中。

该数据集包含一个图片表，用于存储一系列栅格图片的元数据，这些元数据遵循 STAC 项目规范。图片表类似于 Earth Engine 图片集合 (ImageCollection)。

表中的每一行都对应于一个栅格图片，列中包含图片属性和元数据。每个图片的栅格 ID 都存储在 assets.image.href 列中。在查询中使用此 ID 作为 raster_id 参数值来引用参考图片。

使用属性列过滤表格，以选择符合条件的特定图片或图片子集。如需详细了解可用频段、像素大小和属性定义，请打开表格，然后点击图片详情标签页。

每个图片表都包含一个相应的 *_metadata 表，用于提供图片表的辅助信息。

例如，ERA5-Land 数据集提供每日气候变量统计信息，并且可公开获取。climate 表包含多个栅格 ID。以下查询使用 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 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 函数支持存储在 Cloud Storage 存储桶中的光栅数据，这些存储桶位于以下区域，且数据采用 Cloud Optimized GeoTIFF (COG) 格式：

• US 多区域
• us-central1
• EU 多区域
• europe-west1

以 Cloud Storage URI 的形式提供栅格 ID，例如 gs://bucket/folder/raster.tif。

Earth Engine 图片资产

ST_REGIONSTATS 函数支持为 raster_id 参数传递 Earth Engine 图片资产路径。Earth Engine 光栅数据以单个图片或图片集合的形式提供。这些数据位于 US 区域，并且仅与在 US 区域中运行的查询兼容。如需查找图片的栅格 ID，请按以下步骤操作：

1. 在 Earth Engine 数据目录中搜索您感兴趣的数据集。

2. 如需打开相应条目的说明页面，请点击数据集名称。 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 表示像素无效。 无效像素通常表示缺失或不可靠的数据，例如被云遮挡的区域、传感器异常、处理错误或位于指定边界之外的位置。

如果您未指定权重，系统会自动根据像素位于几何图形内的比例对每个像素进行加权，从而允许按比例纳入区域统计信息。如果几何图形小于像素大小的 1/256，则像素的权重为 0。在这些情况下，除 count 和 area（值为 0）之外，所有统计信息的返回值均为 null。

如果部分相交的像素具有从 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 Sharing 中图片表的说明部分找到每个栅格数据集的像素大小。

更改像素大小会改变与给定地理位置相交的像素数量，从而影响结果及其解读。我们不建议更改生产分析的像素大小。不过，如果您要对查询进行原型设计，增加像素大小可以缩短查询运行时长并降低查询费用，尤其是在处理高分辨率数据时。

如需更改像素大小，请将 options 参数中的 scale 设置为 ST_REGIONSTATS 函数。例如，若要计算 1,000 米像素的统计信息，请使用 options => JSON '{"scale":1000}'，该函数会指示 Earth Engine 以请求的比例对图像进行重采样。如需详细了解 Earth Engine 如何处理重新缩放，请参阅 Google Earth Engine 文档中的缩放。

如果多边形明显小于栅格的像素，计算出的统计信息可能会不准确或为空。在这种情况下，一种替代方法是使用 ST_CENTROID 将多边形替换为其质心点。

结算

当您运行查询时，ST_REGIONSTATS 函数的使用费用会与查询的其余部分分开计费，因为 Earth Engine 会计算函数调用的结果。无论您是使用按需付费还是预留，系统都会根据 BigQuery 服务 SKU 以槽小时为单位向您收取此使用量的费用。如需查看 BigQuery 对 Earth Engine 的调用所产生的费用，请查看您的结算报告，并使用标签按标签键 goog-bq-feature-type（值为 EARTH_ENGINE）进行过滤。如果 ST_REGIONSTATS 函数失败，您无需为使用的任何 Earth Engine 计算付费。

对于每个查询，您可以使用 BigQuery API 中的 jobs.get 方法查看以下信息：

• slotMs 字段，用于显示当 externalService 字段为 EARTH_ENGINE 且 billingMethod 字段为 SERVICES_SKU 时，Earth Engine 消耗的槽毫秒数。
• totalServicesSkuSlotMs 字段，用于显示所有按“BigQuery 服务”SKU 计费的 BigQuery 外部服务所使用的总槽毫秒数。

费用因素

运行 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 光栅函数配额。

注意： 与 BigQuery 中的自定义查询配额一样，此配额为近似值。它是一种用于防止支出超额的保护措施，但不是为了严格限制槽时间。BigQuery 偶尔可能会运行超出配额限制的查询，并且您可能会在未收到整个消耗量的账单的情况下用尽配额。

支持的区域

调用 ST_REGIONSTATS 函数的查询必须在以下某个区域中运行：

• US 多区域
• us-central1
• us-central2
• EU 多区域
• europe-west1

后续步骤

• 不妨尝试一下相关教程，了解如何使用光栅数据分析温度。
• 详细了解 BigQuery 中的地理位置函数。
• 详细了解如何使用地理空间数据。