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.
Scorrere i risultati utilizzando l'API
In determinate circostanze, tutti i metodi *collection*.list
restituiscono risultati paginati. 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 la dimensione della risposta è superiore a
10 MB1 di dati o a maxResults
righe. |
Illimitato | Illimitato | Illimitato |
Tutti gli altri metodi di *collection*.list |
Restituisce risultati paginati se la risposta contiene più di
maxResults righe ed è anche inferiore ai limiti massimi. |
10.000 | Illimitato | 300.000 |
Se il risultato è maggiore del limite di byte o campi, viene
troncato per rientrare nel limite. Se una riga supera il limite di byte o campi,
tabledata.list
può restituire fino a 100 MB di dati1,
in linea con il limite massimo di dimensioni delle righe per i risultati delle query.
Non esiste 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 richiesto
esplicitamente un numero maggiore tramite l'assistenza.
Una pagina è un sottoinsieme del numero totale di righe. Se i risultati occupano più
di una pagina di dati, i dati dei risultati hanno una proprietà pageToken
. Per recuperare la pagina successiva di risultati, effettua un'altra chiamata list
e includi il valore del token come parametro URL denominato pageToken
.
Il metodo tabledata.list
, utilizzato per scorrere i dati della tabella, utilizza un valore di offset di riga o un token di pagina. Per informazioni, consulta Sfogliare i dati delle tabelle.
Iterare i risultati delle librerie client
Le librerie client cloud gestiscono i dettagli di basso livello della paginazione delle API e offrono un'esperienza più simile a un iteratore che semplifica l'interazione con i singoli elementi nelle risposte delle pagine.
I seguenti esempi mostrano la paginazione dei dati delle tabelle BigQuery.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery C#.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Le librerie client Cloud per Go eseguono automaticamente la paginazione per impostazione predefinita, quindi non devi implementarla manualmente, ad esempio:
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Le librerie client Cloud per Node.js eseguono automaticamente la paginazione per impostazione predefinita, quindi non è necessario implementarla manualmente, ad esempio:
PHP
Prima di provare questo esempio, segui le istruzioni di configurazione di PHP nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery PHP.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
La paginazione avviene automaticamente nelle librerie client di Cloud per PHP
utilizzando la funzione generatore rows
, che recupera la pagina successiva di
risultati durante l'iterazione.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Le librerie client di Cloud per Python eseguono automaticamente la paginazione per impostazione predefinita, quindi non è necessario implementarla manualmente, ad esempio:
Ruby
Prima di provare questo esempio, segui le istruzioni di configurazione di Ruby nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Ruby.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi 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 ridondanti agli elenchi
Quando torni indietro di una pagina o vai a pagine arbitrarie utilizzando i valori pageToken
memorizzati nella cache, è possibile che i dati nelle pagine siano cambiati dall'ultima visualizzazione, ma non c'è alcuna indicazione chiara che i dati potrebbero essere cambiati. Per risolvere 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
della pagina 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 il valore ETag restituito dall'API e risponde in base alla corrispondenza o meno dei valori ETag. Puoi utilizzare i tag ETag
per evitare chiamate di elenchi ridondanti nel seguente modo:
Per restituire i valori dell'elenco se sono stati modificati.
Se vuoi restituire una pagina di valori di elenco solo se i valori sono cambiati, puoi effettuare una chiamata di elenco con un ETag archiviato in precedenza utilizzando l'intestazione HTTP "if-none-match". Se l'ETag che fornisci 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
e nessun valore. Un esempio potrebbe essere una pagina web in cui gli utenti compilano periodicamente informazioni archiviate in BigQuery. Se non ci sono modifiche ai tuoi dati, puoi evitare di effettuare chiamate di elenco ridondanti a BigQuery utilizzando l'intestazione if-none-match con i tag ETag.Per restituire i valori dell'elenco se non sono stati modificati.
Se vuoi restituire una pagina di valori di elenco solo se i valori di elenco non sono cambiati, puoi utilizzare l'intestazione HTTP "if-match". BigQuery confronta i valori ETag e restituisce la pagina di risultati se i risultati non sono cambiati oppure restituisce un risultato 412 "Precondition Failed" se la pagina è cambiata.
Sfogliare i risultati della query
Ogni query scrive in una tabella di destinazione. Se non viene fornita alcuna tabella di destinazione, l'API BigQuery compila automaticamente la proprietà della 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 il numero tabledata.list
per leggere i risultati della query.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi 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 trasmetti, 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 di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.
Python
Il metodo
QueryJob.result
restituisce un iterabile 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. - Ottieni lo schema della tabella con il metodo
Client.get_table
. - Crea un 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 nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configurare l'autenticazione per le librerie client.