Leggere i dati con l'API BigQuery utilizzando la paginazione
Questo documento descrive come leggere i dati delle tabelle e i risultati delle query con l'API BigQuery utilizzando la paginazione.
Sfogliare i risultati utilizzando l'API
Tutti i metodi *collection*.list
restituiscono risultati paginati
in determinate circostanze. La proprietà maxResults
limita il numero di risultati per pagina.
Metodo | Criteri di paginazione | Valore predefinito di maxResults |
Valore massimo di maxResults |
Valore massimo di maxFieldValues |
---|---|---|---|---|
tabledata.list |
Restituisce risultati paginati se le dimensioni della risposta superano i 10 MB1 di dati o le maxResults righe. |
Illimitato | Illimitato | Illimitato |
Tutti gli altri metodi *collection*.list |
Restituisce risultati paginati se la risposta è composta da più di
maxResults righe e meno dei limiti massimi. |
10.000 | Illimitato | 300.000 |
Se il risultato è maggiore del limite di byte o di campo, viene tagliato in modo da adattarsi al limite. Se una riga è superiore al limite di byte o campi,
tabledata.list
può restituire fino a 100 MB di dati1,
che è coerente con il limite massimo di dimensioni delle righe per i risultati delle query.
Non è prevista una dimensione minima per pagina e alcune pagine potrebbero restituire più righe di altre.
1La dimensione della riga è approssimativa, poiché si basa sulla rappresentazione interna dei dati di riga. La dimensione massima della riga viene applicata durante alcune fasi dell'esecuzione del job di query.
jobs.getQueryResults
può restituire 20 MB di dati, a meno che non ne sia stato esplicitamente richiesto di più tramite l'assistenza.
Una pagina è un sottoinsieme del numero totale di righe. Se i risultati sono costituiti da più di una pagina di dati, i dati del risultato hanno una proprietà pageToken
. Per recuperare la pagina di risultati successiva, effettua un'altra chiamata list
e includi il valore del token come parametro URL denominato pageToken
.
Il metodo tabledata.list
, utilizzato per sfogliare i dati della tabella, utilizza un valore di offset di riga o un token di pagina. Per informazioni, consulta Visualizzazione dei dati delle tabelle.
Esegui l'iterazione dei risultati delle librerie client
Le librerie client cloud gestiscono i dettagli di basso livello della paginazione dell'API e forniscono un'esperienza più simile a un iteratore che semplifica l'interazione con i singoli elementi nelle risposte della pagina.
Gli esempi riportati di seguito mostrano come eseguire la paginazione dei dati della tabella BigQuery.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione C# riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery C#.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione Go riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Le librerie client di Cloud per Go eseguono la paginazione automaticamente per impostazione predefinita, quindi non è necessario implementarla manualmente, ad esempio:
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione Node.js riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Le librerie client Cloud per Node.js eseguono la paginazione automaticamente per impostazione predefinita, quindi non è necessario implementarla manualmente, ad esempio:
PHP
Prima di provare questo esempio, segui le istruzioni di configurazione PHP riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery PHP.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
La paginazione avviene automaticamente nelle librerie client di Cloud per PHP utilizzando la funzione di generatore rows
, che recupera la pagina successiva dei risultati durante l'iterazione.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Le librerie client di Cloud per Python eseguono la paginazione automaticamente per impostazione predefinita, quindi non è necessario implementarla manualmente, ad esempio:
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione Ruby riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Ruby.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
La paginazione avviene automaticamente nelle librerie client di Cloud per Ruby utilizzando Table#data
e Data#next
.
Richiedi pagine arbitrarie ed evita chiamate all'elenco ridondanti
Quando torni indietro o vai a pagine arbitrarie utilizzando i valori pageToken
memorizzati nella cache, è possibile che i dati nelle pagine siano stati modificati dall'ultima visualizzazione, ma non è presente un'indicazione chiara che lo confermi. Per attenuare questo problema, puoi utilizzare la proprietà etag
.
Ogni metodo collection.list
(tranne Tabledata) restituisce una proprietà etag
nel risultato. Questa proprietà è un hash dei risultati della pagina che può essere utilizzato per verificare se la pagina è cambiata dall'ultima richiesta. Quando invii una richiesta a BigQuery con un valore ETag,
BigQuery lo confronta con il valore ETag restituito dall'API e risponde in base alla corrispondenza dei valori ETag. Puoi utilizzare gli ETag per evitare chiamate agli elenchi ridondanti nel seguente modo:
Per restituire i valori dell'elenco se sono stati modificati.
Se vuoi restituire una pagina di valori dell'elenco solo se i valori sono stati modificati, puoi effettuare una chiamata all'elenco con un ETag memorizzato in precedenza utilizzando l'intestazione HTTP "if-none-match". Se l'ETag fornito non corrisponde a quello sul server, BigQuery restituisce una pagina di nuovi valori di elenco. Se gli ETag corrispondenti, BigQuery restituisce un codice stato
HTTP 304 Not Modified
e nessun valore. Un esempio potrebbe essere una pagina web in cui gli utenti potrebbero compilare periodicamente le informazioni archiviate in BigQuery. Se non vengono apportate modifiche ai dati, puoi evitare di effettuare chiamate all'elenco ridondanti in BigQuery utilizzando l'intestazione if-none-match con gli ETag.Per restituire i valori dell'elenco se non sono stati modificati.
Se vuoi restituire una pagina di valori dell'elenco solo se i valori dell'elenco non sono stati modificati, puoi utilizzare l'intestazione HTTP "if-match". BigQuery abbina i valori ETag e restituisce la pagina dei risultati se i risultati non sono cambiati o restituisce un risultato 412 "Condizione preliminare non riuscita" se la pagina è cambiata.
Sfogliare i risultati delle query
Ogni query scrive in una tabella di destinazione. Se non viene fornita alcuna tabella di destinazione, l'API BigQuery compila automaticamente la proprietà tabella di destinazione con un riferimento a una tabella temporanea anonima.
API
Leggi il campo
jobs.config.query.destinationTable
per determinare la tabella in cui sono stati scritti i risultati della query.
Chiama tabledata.list
per leggere i risultati della query.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione Java riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Per impostare il numero di righe restituite in ogni pagina, utilizza un
job GetQueryResults
e imposta l'opzione pageSize
dell'oggetto QueryResultsOption
che passi, come mostrato nell'
esempio seguente:
TableResult result = job.getQueryResults();
QueryResultsOption queryResultsOption = QueryResultsOption.pageSize(20);
TableResult result = job.getQueryResults(queryResultsOption);
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione Node.js riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Python
Il metodo
QueryJob.result
restituisce un iterable dei risultati della query. In alternativa,
- Leggi la proprietà
QueryJob.destination
. Se questa proprietà non è configurata, viene impostata dall'API su un riferimento a una tabella anonima temporanea. - Recupera lo schema della tabella con il metodo
Client.get_table
. - Crea un oggetto iterabile per tutte le righe della tabella di destinazione con il metodo
Client.list_rows
.
Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.
Per autenticarti in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.