此页面由 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 Resource Viewer (roles/earthengine.viewer)
Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
在 BigQuery 共享中订阅数据集： 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 会发布包含光栅数据的公开数据集。如需订阅包含栅格数据的 Earth Engine 数据集，请按以下步骤操作：

前往共享（Analytics Hub）页面。

前往“共享”页面 (Analytics Hub)
点击 搜索商家信息。
在搜索商家信息字段中，输入 "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 格式存储在位于 US 或 us-central1 区域的 Cloud Storage 存储分区中的光栅数据。将 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 共享中的图片表的说明部分找到每个栅格数据集的像素大小。

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

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

结算

运行查询时，ST_REGIONSTATS 函数的使用量会与查询的其余部分分开计费，因为 Earth Engine 会计算函数调用的结果。无论您使用按需结算还是预订，系统都会按 BigQuery 服务 SKU 下的槽小时数对此类使用情况进行结算。如需查看 BigQuery 对 Earth Engine 的调用所产生的费用，请查看结算报告，然后使用标签按标签键 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 中的地理位置函数。
详细了解如何使用地理空间数据。