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 la paginazione.
Sfogliare 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 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 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 al di sotto dei limiti massimi. |
10.000 | Illimitato | 300.000 |
Se il risultato supera il limite di byte o campi,
tagliato per rientrare nel 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.
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 se non esplicitamente
ha 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 successiva di risultati, crea un'altra list
e includi il valore del token come parametro URL denominato pageToken
.
La tabledata.list
, che viene utilizzato per sfogliare i dati delle tabelle, usa un valore di offset di riga o un
token della pagina. Consulta la sezione Dati della tabella di navigazione.
per informazioni.
Esegui l'iterazione tramite i 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.
I seguenti esempi mostrano il paging attraverso la tabella BigQuery e i dati di Google Cloud.
C#
Prima di provare questo esempio, segui le istruzioni per la configurazione di C# nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API C# BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione Go riportate nella guida rapida all'utilizzo delle librerie client di BigQuery. Per ulteriori informazioni, consulta API Go BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Le librerie client di Cloud per Go l'impaginazione viene eseguita automaticamente per impostazione predefinita, quindi non è necessario implementarla tu, ad esempio:
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione Node.js riportate nella guida rapida all'utilizzo delle librerie client di BigQuery. Per ulteriori informazioni, consulta API Node.js BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura 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 per la configurazione di PHP nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API PHP BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
L'impaginazione avviene automaticamente nelle librerie client Cloud per PHP
utilizzando la funzione del generatore rows
, che recupera la pagina successiva di
durante l'iterazione.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo delle librerie client di BigQuery. Per ulteriori informazioni, consulta API Python BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Librerie client Cloud per Python l'impaginazione viene eseguita automaticamente per impostazione predefinita, quindi non è necessario implementarla tu, ad esempio:
Ruby
Prima di provare questo esempio, segui le istruzioni per la configurazione di Ruby nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Ruby BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura 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 usando la cache
pageToken
, è possibile che i dati nelle tue pagine
sono cambiati dall'ultima visualizzazione, ma non esiste un'indicazione chiara del fatto
i dati potrebbero essere cambiati. Per attenuare questo problema, puoi utilizzare la proprietà etag
.
Ogni metodo collection.list
(ad eccezione di Tabledata) restituisce un
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 confronta il valore dell'ETag con quello restituito da
all'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 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 di elenco con un ETag memorizzato in precedenza utilizzando il metodo HTTP "if-none-match" intestazione. Se l'ETag fornito non corrisponde a quello sul server, BigQuery restituisce una pagina di nuovi valori dell'elenco. Se gli ETag eseguono corrispondenza, BigQuery restituisce lo stato
HTTP 304 Not Modified
e nessun valore. Un esempio potrebbe essere una pagina web in cui gli utenti compilare periodicamente le informazioni archiviate in BigQuery. Se ci sono senza modificare i dati, puoi evitare di effettuare chiamate a 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 hanno non è cambiato, puoi utilizzare HTTP "if-match" intestazione. BigQuery associa i valori ETag e restituisce la pagina di o se i risultati non sono cambiati o restituisce un errore 412 "Precondizione Operazione non riuscita" se la pagina è stata modificata.
Scorrere 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à tabella di destinazione con un riferimento a una tabella temporanea anonima.
API
Leggi
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 nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura 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 per la configurazione di Node.js nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Node.js BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.
Python
La
QueryJob.result
restituisce un'iterazione dei risultati della query. In alternativa,
- Leggi
QueryJob.destination
proprietà. Se questa proprietà non è configurata, viene impostata dall'API su un valore riferimento a un modello anonimo temporaneo dalla tabella. - Recupera lo schema della tabella con il metodo
Client.get_table
. - Crea un iterazione su tutte le righe della tabella di destinazione con
Client.list_rows
.
Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo delle librerie client di BigQuery. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.