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 facilement 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 et renvoie les résultats directement au client pour qu'il puisse les consulter ou les utiliser 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 Présentation des EECU).
Le transfert de données vers Earth Engine n'entraîne aucun coût BigQuery supplémentaire. L'utilisation de BigQuery correspondante sera visible dans le tableau de bord des API Google Cloud du projet utilisé (voir Surveiller l'utilisation des API), mais aucun coût ne sera facturé pour la lecture des 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 la documentation sur l'exécution d'une 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 un job de requête BigQuery distinct (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 jobs : accédez à l'historique des six derniers mois des exécutions de requêtes de votre projet (pour en savoir plus, consultez Lister les jobs).
- 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 du cache, ce qui évite des frais inutiles (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 Présentation des EECU). De plus, l'exécution d'une requête est facturée à l'appelant selon le modèle de facturation BigQuery.
Le transfert de données vers Earth Engine n'entraîne aucun coût BigQuery supplémentaire. L'utilisation de BigQuery correspondante sera visible dans le tableau de bord des API Google Cloud du projet utilisé (voir Surveiller l'utilisation des API), mais aucun coût ne sera facturé pour la lecture des 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. Tout job BigQuery qui dépasse cette limite échouera et ne sera pas facturé. La valeur par défaut de maxBytesBilled est de 100 Go. Si votre appel est bloqué parce que vous avez dépassé cette limite, vous pouvez spécifier une autre valeur dans votre script.
Conditions préalables 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 standards Earth Engine, 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 et des jobs de lecture dans le projet cible. Voici les autorisations BigQuery spécifiques requises :
bigquery.tables.get(sur n'importe quelle table consultée)bigquery.tables.getData(sur n'importe quelle table consultée)bigquery.readSession.createbigquery.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
Chaque ee.FeatureCollection peut être filtré à l'aide de la méthode .filter(Filter). Pour permettre aux utilisateurs de Google Earth Engine de bénéficier du traitement hautement parallélisé des données tabulaires BigQuery, nous traduisons les filtres Earth Engine dans un langage compréhensible par BigQuery et les envoyons avec une demande de lecture de table. Cette approche permet en effet de déplacer le traitement des filtres vers la pile BigQuery, mais elle est également soumise à deux limites :
Comme toutes les autres requêtes dans BigQuery (voir les quotas BigQuery), cette requête est limitée à 10 Mo. Cela signifie que les filtres transmis ne peuvent pas être trop complexes. Si vous dépassez 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 fréquente de cette erreur. Pour résoudre ce problème, envisagez d'utiliser ee.Geometry.simplify() sur l'objet concerné.
Certains filtres Earth Engine plus complexes ne peuvent pas être convertis en leurs équivalents BigQuery. Par exemple, BigQuery n'accepte pas les vérifications d'égalité ARRAY. Dans ce cas, nous ne traduisons pas le filtre et l'appliquons plutôt 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 collecte de la manière suivante :
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 peut se comporter de manière inattendue. L'index de caractéristiques doit être une chaîne non vide. Par conséquent, le chargement d'une table BigQuery avec une valeur non chaîne ou
nullpour une colonnesystem: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 appuyer sur les index pour qu'ils correspondent aux mêmes caractéristiques. Par conséquent, si l'indexation précise des données uniques est importante pour l'appelant, nous vous recommandons d'ajouter manuellement la colonne
system:indexdans 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 atteignez cette limite, l'erreur suivante s'affichera :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 lire uniquement les colonnes nécessaires ou d'utiliser
ee.FeatureCollection.runBigQuery()pour prétraiter la table dans BigQuery et réduire la quantité de données récupérées.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 n'importe quelle taille, le traitement de volumes de données plus importants augmentera les coûts des requêtes.La taille du filtre traduit est limitée à 10 Mo. Pour en savoir plus, consultez la section Filtrer les données.
L'utilisation de
ee.FeatureCollection.loadBigQueryTable()ouee.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. Toute tentative de chargement de données à partir d'une telle table génère une erreur "table introuvable".Pour contourner ce problème, exécutez
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')
Joindre des tables BigQuery avec des ID générés automatiquement sur
system:indexpeut entraîner des comportements inattendus. Pour éviter cela, envisagez d'ajouter manuellementsystem:indexà la table BigQuery 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 BigQuery générés automatiquement. Envisagez de spécifier une autre clé à l'aide du paramètrerowKeysdans la méthodeee.FeatureCollection.randomColumn(). Vous pouvez également ajouter manuellement des colonnesrandomousystem:indexà la table source BigQuery. Pour en savoir plus sur l'indexation, consultez la section Indexation des données.