Leggere i dati con l'API BigQuery utilizzando l'impaginazione
Questo documento descrive come leggere i dati delle tabelle e le query sui risultati con l'API BigQuery utilizzando l'impaginazione.
Sfoglia i risultati utilizzando l'API
Tutti i metodi *collection*.list
restituiscono risultati impaginati
in determinate circostanze. La proprietà maxResults
limita il numero di risultati per pagina.
Metodo | Criteri di impaginazione | Valore maxResults predefinito |
Valore massimo maxResults |
Valore massimo maxFieldValues |
---|---|---|---|---|
tabledata.list |
Restituisce risultati impaginati se le dimensioni della risposta superano i 10 MB1 di dati o più di maxResults righe. |
Illimitato | Illimitato | Illimitato |
Tutti gli altri metodi *collection*.list |
Restituisce risultati impaginati se la risposta è superiore a maxResults righe e inferiore ai limiti massimi. |
10.000 | Illimitato | 300.000 |
Se il risultato supera il limite di byte o campi, viene ridotto in base al limite. Se una riga supera il limite di byte o campo, tabledata.list
può restituire fino a 100 MB di dati,1 in linea con il limite massimo di dimensioni delle righe per i risultati della query.
Non esiste una dimensione minima per pagina e alcune pagine potrebbero restituire più righe di altre.
1 La 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 venga richiesto esplicitamente
altro tramite l'assistenza.
Una pagina è un sottoinsieme del numero totale di righe. Se i risultati contengono più
pagine di dati, i dati dei risultati hanno una proprietà
pageToken
. Per recuperare la pagina dei 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 la sezione Dati delle tabelle di navigazione.
Esegui l'iterazione tramite i risultati delle librerie client
Le librerie client cloud gestiscono i dettagli di basso livello dell'impaginazione delle API e forniscono un'esperienza più simile a un iteratore che semplifica l'interazione con i singoli elementi nelle risposte delle pagine.
I seguenti esempi mostrano il paging tramite i dati delle tabelle BigQuery.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery C#.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Le librerie client di Cloud per Go impaginano automaticamente l'impaginazione per impostazione predefinita, quindi non devi implementare personalmente l'impaginazione, ad esempio:
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Le librerie client Cloud per Node.js impaginano automaticamente l'impaginazione per impostazione predefinita, quindi non devi implementare personalmente l'impaginazione, ad esempio:
PHP
Prima di provare questo esempio, segui le istruzioni di configurazione di PHP disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery PHP.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
L'impaginazione avviene automaticamente nelle librerie client di Cloud per PHP
mediante la funzione generatore rows
, che recupera la pagina dei risultati
successiva durante l'iterazione.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Le librerie client Cloud per Python impaginano automaticamente l'impaginazione per impostazione predefinita, quindi non devi implementare personalmente l'impaginazione, ad esempio:
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Ruby.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
L'impaginazione viene eseguita automaticamente nelle librerie client di Cloud per Ruby
utilizzando Table#data
e Data#next
.
Richiedi pagine arbitrarie ed evita chiamate a elenchi ridondanti
Quando torni indietro o passi a pagine arbitrarie utilizzando valori pageToken
memorizzati nella cache, è possibile che i dati nelle tue pagine siano stati modificati dall'ultima visualizzazione, ma non vi è alcuna chiara indicazione che i dati possano essere cambiati. Per limitare questo problema, puoi utilizzare la proprietà etag
.
Ogni metodo collection.list
(ad eccezione di Tabledata) restituisce una
proprietà etag
nel risultato. Questa proprietà è un hash dei risultati delle pagine che può essere utilizzato per verificare se la pagina è stata modificata dall'ultima richiesta. Quando invii una richiesta a BigQuery con un valore ETag, BigQuery confronta il valore ETag con quello restituito dall'API e risponde a seconda che i valori ETag corrispondano. Puoi usare gli ETag per evitare chiamate agli elenchi ridondanti, come indicato di seguito:
Per restituire i valori dell'elenco se i valori sono stati modificati.
Se vuoi restituire una pagina di valori 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 all'ETag sul server, BigQuery restituisce una pagina di nuovi valori di elenco. Se gli ETag corrispondono, BigQuery restituisce un codice di stato
HTTP 304 Not Modified
senza valori. Un esempio potrebbe essere una pagina web in cui gli utenti potrebbero inserire periodicamente informazioni archiviate in BigQuery. Se non vengono apportate modifiche ai dati, puoi evitare di effettuare chiamate di elenchi ridondanti a BigQuery utilizzando l'intestazione if-none-match con gli ETag.Per restituire i valori dell'elenco se i valori non sono stati modificati.
Se vuoi restituire una pagina di valori di elenco solo se questi non sono cambiati, puoi utilizzare l'intestazione HTTP "if-match". BigQuery corrisponde ai valori ETag e restituisce la pagina dei risultati se i risultati non sono cambiati o restituisce un risultato 412 "Precondizione non riuscita" se la pagina è cambiata.
Scorrimento tra i risultati della query
Ogni query scrive in una tabella di destinazione. Se non viene fornita alcuna tabella di destinazione, l'API BigQuery completa automaticamente la proprietà della tabella di destinazione con un riferimento a una tabella anonima temporanea.
API
Leggi il campo jobs.config.query.destinationTable
per determinare la tabella in cui sono stati scritti i risultati della query.
Chiama il tabledata.list
per leggere i risultati della query.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Python
Il metodo QueryJob.result
restituisce un'iterazione 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 una versione iterabile su tutte le righe della tabella di destinazione con il metodo
Client.list_rows
.
Prima di provare questo esempio, segui le istruzioni di configurazione di Python disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.