此页面由 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 数据集，请按以下步骤操作：

前往 Sharing (Analytics Hub) 页面。

前往 Sharing (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 函数支持存储在位于 US 或 us-central1 区域的 Cloud Storage 存储分区中的 GeoTIFF 格式的光栅数据。以 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'。

Pixel 权重

您可以为 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 Sharing 中图片表的说明部分找到每个栅格数据集的像素大小。

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

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

结算

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

费用因素

运行 ST_REGIONSTATS 函数时，以下因素会影响计算用量：

输入行数。
您使用的光栅图片。某些栅格是由 Earth Engine 数据目录中的源图片集合创建的合成栅格，生成合成结果所需的计算资源各不相同。
图片的分辨率。
输入地理位置的大小和复杂程度、与地理位置相交的像素数，以及 Earth Engine 读取的图片图块数和字节数。
地球上输入地理位置相对于源图片以及图片投影和分辨率的位置。
- 图像投影可能会使像素变形，尤其是在高纬度或远超出图像预期覆盖范围的像素。
- 对于合成栅格，与输入地理位置相交的源图片数量可能会因区域和时间而异。例如，有些卫星在低纬度或高纬度地区拍摄的图片更多，具体取决于其轨道和数据收集参数，或者可能会因大气条件变化而省略图片。
include 或 band_name 实参中使用的公式，以及这些公式涉及的波段数量。
之前结果的缓存。

控制费用

如需控制与 ST_REGIONSTATS 函数相关的费用，您可以调整配额，该配额用于控制该函数可消耗的 slot 时间量。默认值为每天 350 个时段小时数。当您查看配额时，请过滤指标列表以显示 earthengine.googleapis.com/bigquery_slot_usage_time，从而查看与来自 BigQuery 的调用关联的 Earth Engine 配额。如需了解详情，请参阅 Google Earth Engine 文档中的 BigQuery 栅格函数配额。

限制

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

US
us-central1
us-central2

后续步骤

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