从 BigQuery 中读取

本页介绍了如何使用 ee.FeatureCollection.loadBigQueryTable() 和 ee.FeatureCollection.runBigQuery() 方法将 BigQuery 表作为 ee.FeatureCollection 对象集成到 Earth Engine 工作流中。

从 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())

结算

与任何其他 Earth Engine 方法一样，系统会将处理请求期间使用的 EECU 小时数的费用计入调用方（请参阅 EECU 概览）。

将数据传输到 Earth Engine 不会产生额外的 BigQuery 费用。相应的 BigQuery 用量将显示在所用项目的 Google Cloud API 信息中心中（请参阅监控 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 的关键功能：

  • 作业记录：查看项目查询执行情况的 6 个月历史记录（如需了解详情，请参阅列出作业）。
  • 查询缓存：BigQuery 会尽可能自动缓存查询结果。后续相同的查询会从缓存中检索数据，从而避免重复扣款（如需了解详情，请参阅使用缓存的查询结果）

如需了解查询或如何在 BigQuery 中使用查询，请参阅 BigQuery 文档。

结算

与任何其他 Earth Engine 方法一样，系统会向调用方收取处理请求期间使用的 EECU 费用（请参阅 EECU 概览）。此外，系统会根据 BigQuery 结算模型向调用方按运行查询的次数收费。

将数据传输到 Earth Engine 不会产生额外的 BigQuery 费用。相应的 BigQuery 用量将显示在所用项目的 Google Cloud API 信息中心中（请参阅监控 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.create
  • bigquery.jobs.create

如需详细了解如何管理权限，请参阅 BigQuery 访问权限控制文档。

数据过滤

您可以使用 .filter(Filter) 方法过滤每个 ee.FeatureCollection。为了让 Google Earth Engine 用户能够受益于高度并行的 BigQuery 表格数据处理，我们会将 Earth Engine 过滤条件转换为 BigQuery 能够理解的语言，并将其与表读取请求一起发送。这种方法确实会将过滤条件处理移至 BigQuery 堆栈，但也存在以下两个限制：

  1. 与 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()。

  2. 某些较为复杂的 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')

  • 对具有自动生成 ID 的 BigQuery 表按 system:index 联接可能会导致意外行为。为避免出现这种情况，不妨考虑手动将 system:index 添加到 BigQuery 表中，或按其他属性联接表。如需详细了解索引编制，请参阅“数据索引编制”部分。

  • ee.FeatureCollection.randomColumn() 方法不适用于 BigQuery 自动生成的 ID。不妨考虑在 ee.FeatureCollection.randomColumn() 方法中使用 rowKeys 参数指定备用密钥。您还可以手动向 BigQuery 源表添加 random 或 system:index 列。如需详细了解索引编制，请参阅“数据索引编制”部分。