Lettura da BigQuery

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

Caricare 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 interattivo di Earth Engine, restituendo i risultati direttamente al client 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 EECU all'ora utilizzate durante l'elaborazione della richiesta viene fatturato al chiamante come per qualsiasi altro metodo Earth Engine (vedi Panoramica delle EECU).

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

Esegui query sui dati da BigQuery

Il metodo ee.FeatureCollection.runBigQuery() esegue una query SQL BigQuery e restituisce i risultati come oggetto ee.FeatureCollection (consulta la documentazione sull'esecuzione di 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 Esegui una query), consentendoti di utilizzare le funzionalità chiave di BigQuery:

• Cronologia job: accedi a una cronologia di sei mesi delle esecuzioni di query del progetto (scopri di più in Elenco job).
• Memorizzazione nella cache delle query: BigQuery memorizza automaticamente nella cache i risultati delle query quando possibile. Le query identiche successive recuperano i dati dalla cache, evitando addebiti ridondanti (scopri di più in Utilizzo dei 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 al chiamante come per qualsiasi altro metodo Earth Engine (vedi Panoramica delle EECU). Inoltre, l'esecuzione di una query viene addebitata al chiamante in base al modello di fatturazione BigQuery.

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

Per controllare i potenziali costi associati a ee.FeatureCollection.runBigQuery(), il parametro maxBytesBilled funge da salvaguardia. Qualsiasi job BigQuery che supera 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à, il progetto Cloud del chiamante deve avere 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 viene fatto 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 a BigQuery.

Filtro dei dati

Ogni ee.FeatureCollection può essere filtrato utilizzando il metodo .filter(Filter). Per consentire agli utenti di Google Earth Engine di usufruire dell'elaborazione dei dati tabulari BigQuery altamente parallelizzata, traduciamo i filtri 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 è soggetto anche a due limitazioni:

1. Come ogni altra query in BigQuery (vedi Quote di BigQuery), questa richiesta è limitata a 10 MB. Ciò significa che i filtri superati non possono essere eccessivamente complicati. Se viene raggiunto 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.

   Il filtro per geometrie che contengono molti vertici è una causa comune di questo errore. Per risolvere il problema, valuta la possibilità di utilizzare ee.Geometry.simplify() sull'oggetto problematico.

2. Alcuni filtri Earth Engine più complessi non possono essere convertiti nei loro equivalenti BigQuery. Ad esempio, BigQuery non supporta i controlli di uguaglianza ARRAY. In questi casi, non traduciamo il filtro e 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 delle funzionalità deve essere una stringa non vuota, quindi il caricamento della tabella BigQuery con un valore non stringa o null per una colonna system:index non riuscirà.

• 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 le stesse, 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

• La dimensione di tutte le colonne selezionate della tabella a cui viene fatto riferimento in una chiamata ee.FeatureCollection.loadBigQueryTable() è limitata a 400 GB. Il raggiungimento di questo limite genera 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 leggere solo le colonne necessarie o di utilizzare ee.FeatureCollection.runBigQuery() per preelaborare 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 delle query. Sebbene le tabelle di origine possano avere 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, valuta la possibilità di eseguire ee.FeatureCollection.runBigQuery() con una query che specifica 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 in base a system:index per le tabelle BigQuery con ID generati automaticamente può comportare comportamenti imprevisti. Per evitare che ciò accada, valuta la possibilità di aggiungere system:index alla tabella BigQuery manualmente o unire la tabella a una proprietà diversa. Scopri di più sull'indicizzazione nella sezione 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 Indicizzazione dei dati.