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 grande.

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

Facturación

El costo de las horas de 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).

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 utilizado (consulta Cómo supervisar el uso de la API), pero no se generará 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 devuelve los resultados como un objeto ee.FeatureCollection (consulta el documento sobre cómo ejecutar una consulta para obtener más información sobre las consultas).

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

Consultas de BigQuery

Cada llamada a ee.FeatureCollection.runBigQuery() inicia un trabajo de consulta de BigQuery independiente (consulta más información sobre las consultas en la documentación de Ejecuta una consulta), lo que te permite usar las capacidades 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).
• Almacenamiento en 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 (consulta 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 utilizado (consulta Cómo supervisar el uso de la API), pero no se generará 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 medida de seguridad. Cualquier trabajo de BigQuery que supere este límite fallará y no se facturará. El valor predeterminado de maxBytesBilled es 100 GB. Si tu llamada se bloquea por exceder este límite, puedes especificar un valor diferente en tu 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 de la página Habilitar 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 que se requieren son los siguientes:

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

Consulta la documentación sobre el 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 paralelizado, traducimos los filtros de Earth Engine a un lenguaje que BigQuery pueda comprender y los enviamos junto con una solicitud de tabla de lectura. Este enfoque, de hecho, 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 en BigQuery (consulta las cuotas de BigQuery), esta solicitud está limitada a un tamaño de 10 MB. Esto significa que los filtros aprobados no pueden ser demasiado complicados. Si se alcanza el límite de 10 MB, se generará 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 de Earth Engine más complejos 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 cambio, lo aplicamos en Earth Engine después de leer los datos.

Indexación de datos

Las colecciones de Earth Engine se basan en la indexación interna, 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 usamos para indexar FeatureCollection.

  En esos casos, el llamador debe asegurarse de que los índices sean únicos. De lo contrario, es posible que la colección se comporte de forma inesperada. El índice de atributos debe ser una cadena no vacía, por lo que fallará la carga de la tabla de BigQuery con un valor no 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 los mismos componentes. Por lo tanto, si la indexación de datos precisamente únicos es importante para el llamador, recomendamos agregar 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 se alcanza este límite, se generará 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 leer solo las columnas necesarias o 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 los tamaños de los resultados de las consultas. Si bien las tablas de origen pueden tener un tamaño arbitrario, procesar volúmenes de datos más grandes aumentará los costos de las consultas.

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

• El uso de ee.FeatureCollection.loadBigQueryTable() o ee.FeatureCollection.runBigQuery() no está disponible en las apps de Earth Engine.

Advertencias

• El ee.FeatureCollection.loadBigQueryTable() no admite recursos de conjuntos de datos vinculados. Si intentas cargar datos de esa tabla, se produce 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:

  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')
        

• Unir 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 de BigQuery. Considera especificar una clave alternativa con el parámetro rowKeys en el método ee.FeatureCollection.randomColumn(). También puedes agregar manualmente columnas random o system:index 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.