Leggi da BigQuery

Questa pagina descrive come integrare le tabelle BigQuery nei workflow di Earth Engine come oggetti ee.FeatureCollection utilizzando i metodi ee.FeatureCollection.loadBigQueryTable() e ee.FeatureCollection.runBigQuery().

Carica i dati da BigQuery

La funzione ee.FeatureCollection.loadBigQueryTable() legge senza problemi una tabella BigQuery in un oggetto ee.FeatureCollection. Si connette a una tabella specificata, converte tutti i tipi di dati, applica i filtri e i selettori necessari e aggiunge l'indicizzazione alla raccolta, se necessario. La funzione utilizza l'ambiente collaborativo di Earth Engine, restituisce i risultati direttamente al cliente per essere visualizzati o utilizzati come componente di un'analisi più ampia.

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

Fatturazione

Il costo delle ore EECU utilizzate durante l'elaborazione della richiesta viene addebitato all'chiamante come per qualsiasi altro metodo di Earth Engine (consulta la Panoramica delle EECU).

Non sono previsti costi aggiuntivi di BigQuery associati al trasferimento dei dati in Earth Engine. L'utilizzo corrispondente di BigQuery sarà visibile nella dashboard dell'API Google Cloud del progetto utilizzato (vedi Monitorare l'utilizzo dell'API), ma non verrà addebitato alcun costo per la lettura dei dati di BigQuery in questo modo.

Esegui query sui dati di BigQuery

Il metodo ee.FeatureCollection.runBigQuery() esegue una query SQL di BigQuery e restituisce i risultati come oggetto ee.FeatureCollection (consulta il documento Esegui una query per saperne di più sulle query).

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

Query BigQuery

Ogni chiamata a ee.FeatureCollection.runBigQuery() avvia un job di query BigQuery separato (scopri di più sulle query nella documentazione su come eseguire una query), consente di utilizzare le funzionalità principali di BigQuery:

  • Cronologia dei job: accedi a una cronologia di sei mesi delle esecuzioni di query del tuo progetto (scopri di più in Elenca job).
  • Memorizzazione nella cache delle query: BigQuery memorizza automaticamente nella cache i risultati delle query, se possibile. Le query identiche successive recuperano i dati dalla cache, evitando addebiti ridondanti (scopri di più in Utilizzare i risultati delle query memorizzati nella cache).

Per scoprire di più sulle query o su come utilizzarle in BigQuery, consulta la documentazione di BigQuery.

Fatturazione

Il costo delle EECU utilizzate durante l'elaborazione della richiesta viene addebitato all'utente chiamante come per qualsiasi altro metodo di Earth Engine (consulta la panoramica delle EECU). Inoltre, l'esecuzione di una query viene fatturata all'utente chiamante in base al modello di fatturazione di BigQuery.

Non sono previsti costi aggiuntivi di BigQuery associati al trasferimento dei dati in Earth Engine. L'utilizzo corrispondente di BigQuery sarà visibile nella dashboard dell'API Google Cloud del progetto utilizzato (vedi Monitorare l'utilizzo dell'API), ma la lettura dei dati di BigQuery in questo modo non comporta costi.

Per controllare i potenziali costi associati a ee.FeatureCollection.runBigQuery(), il parametro maxBytesBilled funge da salvaguardia. Qualsiasi job BigQuery che superi questo limite non andrà a buon fine e non verrà fatturato. Il valore predefinito di maxBytesBilled è 100 GB. Se la chiamata viene bloccata per superamento di questo limite, puoi specificare un valore diverso nello script.

Prerequisiti e autorizzazioni

Per utilizzare questa funzionalità, è necessario che nel progetto Cloud dell'utente che chiama siano abilitate l'API BigQuery e l'API BigQuery Storage. Segui le istruzioni riportate nella pagina Abilita API per abilitare le API appropriate.

Oltre ai ruoli e alle autorizzazioni standard di Earth Engine, devi disporre dell'accesso in lettura alla tabella BigQuery a cui fai riferimento e dell'autorizzazione per creare sessioni di lettura e job nel progetto di destinazione. Le autorizzazioni BigQuery specifiche richieste sono:

  • bigquery.tables.get (in qualsiasi tabella a cui è stato eseguito l'accesso)
  • bigquery.tables.getData (in qualsiasi tabella a cui è stato eseguito l'accesso)
  • bigquery.readSession.create
  • bigquery.jobs.create

Per informazioni dettagliate sulla gestione delle autorizzazioni, consulta la documentazione sul controllo dell'accesso di BigQuery.

Filtro dei dati

A ogni ee.FeatureCollection è possibile applicare un filtro utilizzando il metodo .filter(Filter). Per consentire agli utenti di Google Earth Engine di usufruire dell'elaborazione di dati tabulari BigQuery altamente parallelizzata, traduciamo i filtri di Earth Engine in un linguaggio comprensibile da BigQuery e li inviamo insieme a una richiesta di lettura della tabella. Questo approccio sposta l'elaborazione dei filtri nello stack BigQuery, ma è anche soggetto a due limitazioni:

  1. Come ogni altra query in BigQuery (vedi quote di BigQuery), questa richiesta è limitata a 10 MB di dimensione. Ciò significa che i filtri trasmessi non possono essere eccessivamente complicati. Se raggiungi il limite di 10 MB, viene visualizzato il seguente errore:

    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.

    L'applicazione di filtri in base a geometrie contenenti molti vertici è una causa comune di questo errore. Per risolvere il problema, ti consigliamo di utilizzare ee.Geometry.simplify() sull'oggetto problematico.

  2. Alcuni filtri Earth Engine più complicati non possono essere convertiti nei rispettivi equivalenti BigQuery. Ad esempio, BigQuery non supporta i controlli di uguaglianza ARRAY. In questi casi, non traduciamo il filtro, ma lo applichiamo in Earth Engine dopo aver letto i dati.

Indicizzazione dei dati

Le raccolte Earth Engine si basano sull'indicizzazione interna, mentre BigQuery sconsiglia di mantenere le tabelle indicizzate. Per far funzionare insieme questi due sistemi, creiamo gli indici delle raccolte nel seguente modo:

  • Se la tabella BigQuery contiene una colonna denominata system:index, la utilizziamo per indicizzare FeatureCollection.

    In questi casi, è responsabilità del chiamante assicurarsi che gli indici siano univoci. In caso contrario, la raccolta potrebbe comportarsi in modo imprevisto. L'indice di funzionalità deve essere una stringa non vuota, pertanto il caricamento della tabella BigQuery con un valore diverso da una stringa o null per una colonna system:index non andrà a buon fine.

  • Se la tabella BigQuery non contiene la colonna system:index, viene generata automaticamente.

    Gli indici tra due richieste di lettura sono stabili, ma solo se le richieste sono esattamente uguali, tenendo conto dei filtri. In caso contrario, non possiamo fare affidamento sugli indici per corrispondere alle stesse funzionalità. Pertanto, se l'indicizzazione dei dati univoci è importante per il chiamante, consigliamo di aggiungere manualmente la colonna system:index in BigQuery.

Limitazioni

  • Le dimensioni di tutte le colonne selezionate della tabella a cui viene fatto riferimento in una chiamata ee.FeatureCollection.loadBigQueryTable() sono limitate a 400 GB. Se raggiungi questo limite, verrà visualizzato il seguente errore:

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

    In questi casi, valuta la possibilità di scegliere selettori più restrittivi per le colonne necessarie di sola lettura o di utilizzare ee.FeatureCollection.runBigQuery() per pre-elaborare la tabella in BigQuery e ridurre la quantità di dati recuperati.

  • Il metodo ee.FeatureCollection.runBigQuery() impone un limite di 10 GB alle dimensioni dei risultati della query. Sebbene le tabelle di origine possano essere di dimensioni arbitrarie, l'elaborazione di volumi di dati più grandi aumenterà i costi delle query.

  • La dimensione del filtro tradotto è limitata a 10 MB. Per informazioni dettagliate, consulta la sezione Filtro dei dati.

  • L'utilizzo di ee.FeatureCollection.loadBigQueryTable() o ee.FeatureCollection.runBigQuery() non è disponibile con le app Earth Engine.

Avvertenze

  • ee.FeatureCollection.loadBigQueryTable() non supporta le risorse dei set di dati collegati. Il tentativo di caricare i dati da questa tabella genera l'errore "Tabella non trovata".

    Come soluzione alternativa, ti consigliamo di eseguire ee.FeatureCollection.runBigQuery() con una query che specifichi la tabella richiesta dal set di dati collegato. Ad esempio:

    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'unione su system:index per le tabelle BigQuery con ID generati automaticamente può portare a comportamenti imprevisti. Per evitare che ciò accada, valuta la possibilità di aggiungere system:index alla tabella BigQuery manualmente o di unire la tabella a una proprietà diversa. Scopri di più sull'indicizzazione nella sezione sull'indicizzazione dei dati.

  • Il metodo ee.FeatureCollection.randomColumn() non funziona con gli ID generati automaticamente da BigQuery. Valuta la possibilità di specificare una chiave alternativa utilizzando il parametro rowKeys nel metodo ee.FeatureCollection.randomColumn(). Puoi anche aggiungere manualmente colonne random o system:index alla tabella di origine BigQuery. Scopri di più sull'indicizzazione nella sezione sull'indicizzazione dei dati.