Procéder à la lecture dans BigQuery

Cette page explique comment intégrer des tables BigQuery dans des workflows Earth Engine en tant qu'objets ee.FeatureCollection, à l'aide des méthodes ee.FeatureCollection.loadBigQueryTable() et ee.FeatureCollection.runBigQuery().

Charger des données à partir de BigQuery

La fonction ee.FeatureCollection.loadBigQueryTable() lit de manière transparente une table BigQuery dans un objet ee.FeatureCollection. Il se connecte à une table spécifiée, convertit tous les types de données, applique les filtres et sélecteurs nécessaires, et ajoute l'indexation à la collection si nécessaire. La fonction utilise l'environnement interactif d'Earth Engine, renvoyant les résultats directement au client pour qu'il les affiche ou les utilise comme composant d'une analyse plus vaste.

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

Facturation

Le coût des heures d'EECU utilisées lors du traitement de la requête est facturé à l'appelant, comme pour toute autre méthode Earth Engine (voir la présentation des EECU).

Le transfert des données vers Earth Engine n'entraîne aucuns frais BigQuery supplémentaires. L'utilisation correspondante de BigQuery sera visible dans le tableau de bord de l'API Google Cloud du projet utilisé (voir Surveiller l'utilisation de l'API), mais aucun coût ne sera facturé pour lire les données BigQuery de cette manière.

Interroger des données à partir de BigQuery

La méthode ee.FeatureCollection.runBigQuery() exécute une requête SQL BigQuery et renvoie les résultats sous la forme d'un objet ee.FeatureCollection (pour en savoir plus sur les requêtes, consultez Exécuter un document de requête).

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

Requêtes BigQuery

Chaque appel à ee.FeatureCollection.runBigQuery() lance une tâche de requête BigQuery distincte (pour en savoir plus sur les requêtes, consultez la documentation Exécuter une requête). Vous pouvez ainsi utiliser les principales fonctionnalités de BigQuery:

  • Historique des tâches: accédez à l'historique de six mois des exécutions de requêtes de votre projet (pour en savoir plus, consultez Liste des tâches).
  • Mise en cache des requêtes: BigQuery met automatiquement en cache les résultats des requêtes lorsque cela est possible. Les requêtes identiques ultérieures récupèrent les données à partir du cache, ce qui évite les frais redondants (pour en savoir plus, consultez Utiliser les résultats de requête mis en cache).

Pour en savoir plus sur les requêtes ou sur leur utilisation dans BigQuery, consultez la documentation BigQuery.

Facturation

Le coût des EECU utilisés lors du traitement de la requête est facturé à l'appelant comme pour toute autre méthode Earth Engine (voir la présentation des EECU). De plus, l'exécution d'une requête est facturée à l'appelant conformément au modèle de facturation BigQuery.

Le transfert des données vers Earth Engine n'entraîne aucuns frais BigQuery supplémentaires. L'utilisation correspondante de BigQuery sera visible dans le tableau de bord de l'API Google Cloud du projet utilisé (voir Surveiller l'utilisation de l'API), mais aucun coût ne sera facturé pour lire les données BigQuery de cette manière.

Pour contrôler les coûts potentiels associés à ee.FeatureCollection.runBigQuery(), le paramètre maxBytesBilled sert de protection. Toute tâche BigQuery qui dépasse cette limite échouera et ne sera pas facturée. La valeur par défaut de maxBytesBilled est de 100 Go. Si votre appel est bloqué en raison d'un dépassement de cette limite, vous pouvez spécifier une autre valeur dans votre script.

Prérequis et autorisations

Pour utiliser cette fonctionnalité, l'API BigQuery et l'API BigQuery Storage doivent être activées dans le projet Cloud de l'appelant. Suivez les instructions de la page Activer l'API pour activer les API appropriées.

En plus des rôles et autorisations Earth Engine standards, vous devez disposer d'un accès en lecture à la table BigQuery référencée, ainsi que de l'autorisation de créer des sessions de lecture et des tâches dans le projet cible. Les autorisations BigQuery spécifiques requises sont les suivantes:

  • bigquery.tables.get (sur n'importe quelle table consultée)
  • bigquery.tables.getData (sur n'importe quelle table consultée)
  • bigquery.readSession.create
  • bigquery.jobs.create

Pour en savoir plus sur la gestion des autorisations, consultez la documentation sur le contrôle des accès dans BigQuery.

Filtrage des données

Vous pouvez filtrer chaque ee.FeatureCollection à l'aide de la méthode .filter(Filter). Pour permettre aux utilisateurs de Google Earth Engine de bénéficier d'un traitement des données tabulaires BigQuery hautement parallélisé, nous traduisons les filtres Earth Engine dans un langage compréhensible par BigQuery et les envoyons avec une requête de lecture de table. Cette approche déplace en effet le traitement des filtres vers la pile BigQuery, mais elle est également soumise à deux limites:

  1. Comme toutes les autres requêtes dans BigQuery (voir Quotas BigQuery), cette requête est limitée à 10 Mo. Cela signifie que les filtres transmis ne peuvent pas être trop compliqués. Si vous atteignez la limite de 10 Mo, l'erreur suivante s'affiche:

    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.

    Le filtrage par géométries contenant de nombreux sommets est une cause courante de cette erreur. Pour résoudre ce problème, envisagez d'utiliser ee.Geometry.simplify() sur l'objet problématique.

  2. Certains filtres Earth Engine plus complexes ne peuvent pas être convertis en équivalents BigQuery. Par exemple, BigQuery n'accepte pas les vérifications d'égalité ARRAY. Dans ce cas, nous ne traduisons pas le filtre, mais nous l'appliquons dans Earth Engine après avoir lu les données.

Indexation des données

Les collections Earth Engine s'appuient sur l'indexation interne, tandis que BigQuery déconseille de conserver les tables indexées. Pour que ces deux systèmes fonctionnent ensemble, nous créons des index de collection comme suit:

  • Si la table BigQuery contient une colonne nommée system:index, nous l'utilisons pour indexer FeatureCollection.

    Dans ce cas, il appartient à l'appelant de s'assurer que les index sont uniques. Sinon, la collection risque de se comporter de manière inattendue. L'indice de la fonctionnalité doit être une chaîne non vide. Le chargement de la table BigQuery avec une valeur autre qu'une chaîne ou null pour une colonne system:index échouera.

  • Si la table BigQuery ne contient pas la colonne system:index, elle est générée automatiquement.

    Les index entre deux requêtes de lecture sont stables, mais uniquement si les requêtes sont exactement les mêmes, en tenant compte des filtres. Sinon, nous ne pouvons pas nous fier aux index pour qu'ils correspondent aux mêmes éléments géographiques. Par conséquent, si l'indexation des données uniques est importante pour l'appelant, nous vous recommandons d'ajouter manuellement la colonne system:index dans BigQuery.

Limites

  • La taille de toutes les colonnes sélectionnées de la table référencée dans un appel ee.FeatureCollection.loadBigQueryTable() est limitée à 400 Go. Si vous dépassez cette limite, l'erreur suivante s'affiche:

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

    Dans ce cas, envisagez de choisir des sélecteurs plus restrictifs pour les colonnes nécessaires en lecture seule ou d'utiliser ee.FeatureCollection.runBigQuery() pour prétraiter la table dans BigQuery et réduire la quantité de données extraites.

  • La méthode ee.FeatureCollection.runBigQuery() impose une limite de 10 Go à la taille des résultats de requête. Bien que les tables sources puissent être de taille arbitraire, le traitement de volumes de données plus importants augmente les coûts de requête.

  • La taille du filtre traduit est limitée à 10 Mo. Pour en savoir plus, consultez la section Filtrage des données.

  • L'utilisation de ee.FeatureCollection.loadBigQueryTable() ou ee.FeatureCollection.runBigQuery() n'est pas disponible avec les applications Earth Engine.

Mises en garde

  • ee.FeatureCollection.loadBigQueryTable() n'est pas compatible avec les ressources des ensembles de données associés. Si vous tentez de charger des données à partir d'une telle table, le message d'erreur "Table introuvable" s'affiche.

    Pour contourner le problème, envisagez d'exécuter ee.FeatureCollection.runBigQuery() avec une requête spécifiant la table demandée à partir de l'ensemble de données associé. Exemple :

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

  • L'association sur system:index pour les tables BigQuery avec des ID générés automatiquement peut entraîner des comportements inattendus. Pour éviter cela, envisagez d'ajouter system:index à la table BigQuery manuellement ou de joindre la table à une autre propriété. Pour en savoir plus sur l'indexation, consultez la section Indexation des données.

  • La méthode ee.FeatureCollection.randomColumn() ne fonctionne pas avec les ID générés automatiquement par BigQuery. Envisagez de spécifier une autre clé à l'aide du paramètre rowKeys dans la méthode ee.FeatureCollection.randomColumn(). Vous pouvez également ajouter manuellement des colonnes random ou system:index à la table source BigQuery. Pour en savoir plus sur l'indexation, consultez la section Indexation des données.