Lee desde BigQuery

En esta página, se describe cómo integrar tablas de BigQuery en flujos de trabajo de Earth Engine como objetos ee.FeatureCollection con los métodos ee.FeatureCollection.loadBigQueryTable() y ee.FeatureCollection.runBigQuery().

Carga datos de BigQuery

La función ee.FeatureCollection.loadBigQueryTable() lee sin problemas una tabla de BigQuery en un objeto ee.FeatureCollection. Se conecta a una tabla especificada, convierte todos los tipos de datos, aplica los filtros y selectores necesarios, y agrega indexación a la colección si es necesario. La función usa el entorno interactivo de Earth Engine y muestra los resultados directamente al cliente para que los vea o los use como componente de un análisis más amplio.

JavaScriptPython
// 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);
      
# 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())

Facturación

El costo de las horas de EECU que se usan durante el procesamiento de la solicitud se factura al llamador como cualquier otro método de Earth Engine (consulta la descripción general de las EECU).

No hay costos adicionales de BigQuery asociados con la transferencia de datos a Earth Engine. El uso correspondiente de BigQuery se podrá ver en el panel de la API de Google Cloud del proyecto que se usa (consulta Cómo supervisar el uso de la API), pero no se incurrirá en ningún costo por leer los datos de BigQuery de esta manera.

Consulta datos de BigQuery

El método ee.FeatureCollection.runBigQuery() ejecuta una consulta en SQL de BigQuery y muestra los resultados como un objeto ee.FeatureCollection (consulta Cómo ejecutar un documento de consulta para obtener más información sobre las consultas).

JavaScriptPython
// 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());
      
# 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())

Consultas de BigQuery

Cada llamada a ee.FeatureCollection.runBigQuery() inicia un trabajo de consulta de BigQuery independiente (obtén más información sobre las consultas en la documentación para ejecutar una consulta), lo que te permite usar las siguientes funciones clave de BigQuery:

  • Historial de trabajos: Accede a un historial de seis meses de las ejecuciones de consultas de tu proyecto (obtén más información en Cómo enumerar trabajos).
  • Caché de consultas: BigQuery almacena automáticamente en caché los resultados de las consultas cuando es posible. Las consultas idénticas posteriores recuperan datos de la caché, lo que evita cargos redundantes (obtén más información en Usa resultados de consultas almacenados en caché).

Para obtener información sobre las consultas o cómo usarlas en BigQuery, consulta la documentación de BigQuery.

Facturación

El costo de las EECU que se usan durante el procesamiento de la solicitud se factura al llamador como para cualquier otro método de Earth Engine (consulta la descripción general de las EECU). Además, la ejecución de una consulta se factura al llamador según el modelo de facturación de BigQuery.

No hay costos adicionales de BigQuery asociados con la transferencia de datos a Earth Engine. El uso correspondiente de BigQuery se podrá ver en el panel de la API de Google Cloud del proyecto que se usa (consulta Cómo supervisar el uso de la API), pero no se incurrirá en ningún costo por leer los datos de BigQuery de esta manera.

Para controlar los posibles costos asociados con ee.FeatureCollection.runBigQuery(), el parámetro maxBytesBilled actúa como protección. Cualquier trabajo de BigQuery que supere este límite fallará y no se facturará. El valor predeterminado de maxBytesBilled es 100 GB. Si se bloquea tu llamada por exceder este límite, puedes especificar un valor diferente en la secuencia de comandos.

Requisitos previos y permisos

Para usar esta función, el proyecto de Cloud del llamador debe tener habilitadas la API de BigQuery y la API de BigQuery Storage. Sigue las instrucciones en la página Habilita la API para habilitar las APIs adecuadas.

Además de los roles y permisos estándar de Earth Engine, debes tener acceso de lectura a la tabla de BigQuery a la que se hace referencia y permiso para crear sesiones y trabajos de lectura en el proyecto de destino. Los permisos específicos de BigQuery necesarios son los siguientes:

  • bigquery.tables.get (en cualquier tabla a la que se accedió)
  • bigquery.tables.getData (en cualquier tabla a la que se accedió)
  • bigquery.readSession.create
  • bigquery.jobs.create

Consulta la documentación de control de acceso de BigQuery para obtener información detallada sobre la administración de permisos.

Filtrado de datos

Cada ee.FeatureCollection se puede filtrar con el método .filter(Filter). Para permitir que los usuarios de Google Earth Engine se beneficien del procesamiento de datos tabulares de BigQuery altamente paralelo, traducimos los filtros de Earth Engine a un lenguaje que BigQuery puede entender y los enviamos junto con una solicitud de tabla de lectura. Este enfoque, en efecto, traslada el procesamiento de filtros a la pila de BigQuery, pero también está sujeto a dos limitaciones:

  1. Al igual que todas las demás consultas de BigQuery (consulta las cuotas de BigQuery), esta solicitud tiene un tamaño limitado a 10 MB. Esto significa que los filtros pasados no pueden ser demasiado complejos. Si se alcanza el límite de 10 MB, se muestra el siguiente error:

    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.

    Filtrar por geometrías que contienen muchos vértices es una causa común de este error. Para resolver este problema, considera usar ee.Geometry.simplify() en el objeto problemático.

  2. Algunos filtros más complejos de Earth Engine no se pueden convertir a sus equivalentes de BigQuery. Por ejemplo, BigQuery no admite verificaciones de igualdad de ARRAY. En esos casos, no traducimos el filtro y, en su lugar, lo aplicamos en Earth Engine después de leer los datos.

Indexación de datos

Las colecciones de Earth Engine dependen del indexado interno, mientras que BigQuery desaconseja mantener las tablas indexadas. Para que esos dos sistemas funcionen juntos, creamos índices de recopilación de la siguiente manera:

  • Si la tabla de BigQuery contiene una columna llamada system:index, la usaremos para indexar FeatureCollection.

    En esos casos, el llamador debe asegurarse de que los índices sean únicos. De lo contrario, la colección podría comportarse de forma inesperada. El índice de atributos debe ser una cadena no vacía, por lo que se producirá un error si se carga la tabla de BigQuery con un valor que no sea de cadena o null para una columna system:index.

  • Si la tabla de BigQuery no contiene la columna system:index, se genera automáticamente.

    Los índices entre dos solicitudes de lectura son estables, pero solo si las solicitudes son exactamente iguales, teniendo en cuenta los filtros. De lo contrario, no podemos confiar en que los índices correspondan a las mismas funciones. Por lo tanto, si el indexado de datos únicos es importante para el llamador, te recomendamos que agregues la columna system:index en BigQuery de forma manual.

Limitaciones

  • El tamaño de todas las columnas seleccionadas de la tabla a la que se hace referencia en una llamada a ee.FeatureCollection.loadBigQueryTable() se limita a 400 GB. Si alcanzas este límite, se mostrará el siguiente error:

    Failed to read table from BigQuery: Requested data size is too large to read. Consider using selectors to specify only required columns.

    En esos casos, considera elegir selectores más restrictivos para las columnas necesarias de solo lectura o considera usar ee.FeatureCollection.runBigQuery() para procesar previamente la tabla en BigQuery y reducir la cantidad de datos recuperados.

  • El método ee.FeatureCollection.runBigQuery() impone un límite de 10 GB en el tamaño de los resultados de las consultas. Aunque las tablas de origen pueden ser de tamaño arbitrario, procesar volúmenes de datos más grandes aumentará los costos de consulta.

  • El tamaño del filtro traducido se limita a 10 MB. Consulta la sección Filtrado de datos para obtener más detalles.

Advertencias

  • ee.FeatureCollection.loadBigQueryTable() no admite recursos de Conjuntos de datos vinculados. Si intentas cargar datos de esa tabla, se mostrará el error “No se encontró la tabla”.

    Como solución alternativa, considera ejecutar ee.FeatureCollection.runBigQuery() con una consulta que especifique la tabla solicitada del conjunto de datos vinculado. Por ejemplo:

    JavaScriptPython
    var features = ee.FeatureCollection.runBigQuery({
  query: 'SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn: 'geo'
});
      
    features = ee.FeatureCollection.runBigQuery(
  query='SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn='geo')

  • Unirse en system:index para tablas de BigQuery con IDs generados automáticamente puede generar comportamientos inesperados. Para evitar que esto suceda, considera agregar system:index a la tabla de BigQuery de forma manual o unir la tabla en una propiedad diferente. Obtén más información sobre la indexación en la sección Indexación de datos.

  • El método ee.FeatureCollection.randomColumn() no funciona con los IDs generados automáticamente por BigQuery. Considera especificar una clave alternativa con el parámetro rowKeys en el método ee.FeatureCollection.randomColumn(). También puedes agregar columnas random o system:index de forma manual a la tabla de origen de BigQuery. Obtén más información sobre la indexación en la sección Indexación de datos.