Leggere i dati con l'API BigQuery utilizzando l'impaginazione
Questo documento descrive come leggere i dati delle tabelle e i risultati delle query con l'API BigQuery utilizzando l'impaginazione.
Scorri i risultati con l'API
In determinate circostanze, tutti i metodi *collection*.list
restituiscono risultati impaginati. La proprietà maxResults
limita il numero di risultati per pagina.
Metodo | Criteri di impaginazione | Valore predefinito di maxResults |
Valore massimo di maxResults |
Valore massimo di maxFieldValues |
---|---|---|---|---|
tabledata.list |
Restituisce risultati impaginati se la dimensione della risposta è superiore a 10 MB1 di dati o a più di maxResults
righe. |
Illimitato | Illimitato | Illimitato |
Tutti gli altri metodi *collection*.list |
Restituisce risultati impaginati se la risposta è superiore a maxResults righe e anche inferiore ai limiti massimi. |
10.000 | Illimitato | 300.000 |
Se il risultato supera il limite di byte o campi, viene tagliato per rientrare nel limite. Se una riga è superiore al limite di byte o di campo,
tabledata.list
può restituire fino a 100 MB di dati1,
che è coerente con il limite massimo per la dimensione delle righe per i risultati della 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 vengano esplicitamente richiesti altri tramite l'assistenza.
Una pagina è un sottoinsieme del numero totale di righe. Se i risultati sono costituiti da più
pagine 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 la pagina dei dati della tabella, utilizza un valore di offset di riga o un token di pagina. Per informazioni, consulta la sezione Navigazione dei dati della tabella.
Esegui l'iterazione tramite i risultati delle librerie client
Le librerie client di Cloud gestiscono i dettagli di basso livello dell'impaginazione 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 il paging dei dati della tabella BigQuery.
C#
Prima di provare questo esempio, segui le istruzioni per la configurazione di C# nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API C# di BigQuery.
Per eseguire l'autenticazione su 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 per la configurazione di Java nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di BigQuery.
Per eseguire l'autenticazione su 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 per la configurazione di Go nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Go di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Le librerie client di Cloud per Go eseguono automaticamente l'impaginazione per impostazione predefinita, quindi non è necessario implementare l'impaginazione manualmente, ad esempio:
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Node.js di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Le librerie client di Cloud per Node.js eseguono automaticamente l'impaginazione per impostazione predefinita, quindi non è necessario implementare l'impaginazione manualmente, ad esempio:
PHP
Prima di provare questo esempio, segui le istruzioni per la configurazione di PHP nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API PHP di BigQuery.
Per eseguire l'autenticazione su 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 utilizzando la funzione del generatore rows
, che recupera la pagina successiva di risultati durante l'iterazione.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Le librerie client di Cloud per Python eseguono automaticamente l'impaginazione per impostazione predefinita, quindi non è necessario implementare l'impaginazione manualmente, ad esempio:
Ruby
Prima di provare questo esempio, segui le istruzioni per la configurazione di Ruby nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Ruby di BigQuery.
Per eseguire l'autenticazione su 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 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 cambiati dall'ultima visualizzazione, ma non vi è alcuna indicazione chiara che i dati possano essere cambiati. Per mitigare 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 di pagina che può essere utilizzato per verificare se la pagina è cambiata dall'ultima richiesta. Quando effettui una richiesta a BigQuery con un valore ETag, BigQuery confronta il valore dell'ETag con quello restituito dall'API e risponde in base alla corrispondenza dei valori dell'ETag. Puoi usare gli ETag per evitare chiamate all'elenco ridondanti come segue:
Per restituire valori dell'elenco se i valori sono stati modificati.
Se vuoi restituire una pagina di valori dell'elenco solo se i valori sono stati modificati, puoi effettuare una chiamata dell'elenco con un ETag memorizzato in precedenza utilizzando l'intestazione "if-none-match" HTTP. Se l'ETag fornito non corrisponde a quello sul server, BigQuery restituisce una pagina di nuovi valori dell'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 possono compilare periodicamente le 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 dell'elenco solo se i valori dell'elenco non sono stati modificati, puoi utilizzare l'intestazione "if-match" HTTP. BigQuery trova i valori ETag e restituisce la pagina dei risultati se i risultati non sono cambiati oppure restituisce un risultato 412 "Precondizione non riuscita" se la pagina è stata modificata.
Scorri i risultati della query
Ogni query scrive in una tabella di destinazione. Se non viene fornita una tabella di destinazione, l'API BigQuery compila 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 tabledata.list
per leggere i risultati della query.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Java di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Per impostare il numero di righe restituite su 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 per la configurazione di Node.js nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Node.js di BigQuery.
Per eseguire l'autenticazione su 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, l'API imposta 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 per la configurazione di Python nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Python di BigQuery.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.