本页面介绍了如何使用 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())
结算
在处理请求期间使用的 EECU 小时数费用会像任何其他 Earth Engine 方法一样向调用方收取（请参阅 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 文档。
结算
在处理请求期间使用的 EECU 的费用会像任何其他 Earth Engine 方法一样向调用方收取（请参阅 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.createbigquery.jobs.create
如需详细了解如何管理权限，请参阅 BigQuery 访问权限控制文档。
数据过滤
可以使用 .filter(Filter) 方法过滤每个 ee.FeatureCollection。为了让 Google Earth Engine 用户能够受益于高度并行化的 BigQuery 表格数据处理，我们将 Earth Engine 过滤器转换为 BigQuery 可理解的语言，并将其与读取表格请求一起发送。此方法确实将过滤条件处理移到了 BigQuery 堆栈，但也受到以下两项限制：
与 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()。
某些更复杂的 Earth Engine 过滤器无法转换为相应的 BigQuery 过滤器。例如，BigQuery 不支持 ARRAY 相等性检查。在这种情况下，我们不会翻译过滤器，而是在读取数据后在 Earth Engine 中应用该过滤器。
数据索引
Earth Engine 集合依赖于内部索引，而 BigQuery 不建议保持表编入索引。为了让这两个系统协同工作，我们以如下方式创建集合索引：
如果 BigQuery 表包含名为
system:index的列，我们会使用该列为 FeatureCollection 编制索引。在这种情况下，调用方应确保索引是唯一的。否则，集合可能会以意想不到的方式出现异常行为。特征索引必须是非空字符串，因此如果加载的 BigQuery 表的
system:index列包含非字符串或null值，则加载会失败。如果 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可能会导致意外行为。为避免这种情况，请考虑手动向 BigQuery 表添加system:index或根据其他属性联接表。如需详细了解索引编制，请参阅数据索引编制部分。ee.FeatureCollection.randomColumn()方法不适用于 BigQuery 自动生成的 ID。考虑使用ee.FeatureCollection.randomColumn()方法中的rowKeys参数指定替代密钥。您还可以手动向 BigQuery 源表中添加random或system:index列。如需详细了解索引编制，请参阅数据索引编制部分。