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 con l'impaginazione.
Scorri i risultati con 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 supera il limite di byte o campi,
tabledata.list
può restituire fino a 100 MB di dati1,
che è coerente con il limite massimo della dimensione delle righe per i risultati della 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 maggiori
di una pagina di dati, i dati dei risultati hanno un pageToken
proprietà. 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 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 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 per la configurazione di Go nel Guida rapida di BigQuery con librerie client. 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 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 ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Le librerie client di Cloud per Node.js l'impaginazione viene eseguita automaticamente per impostazione predefinita, quindi non è necessario implementarla tu, 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 per la configurazione di Python nel Guida rapida di BigQuery con librerie client. 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 ovviare a questo problema, puoi utilizzare etag
proprietà.
Ogni metodo collection.list
(ad eccezione di Tabledata) restituisce un
Proprietà etag
nel risultato. Questa proprietà è un hash della pagina
risultati che possono essere utilizzati per verificare se la pagina è stata modificata dall'ultima volta
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 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 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.
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 tabella di destinazione con un riferimento a un valore anonimo temporaneo dalla tabella.
API
Leggi
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 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.
Per impostare il numero di righe restituite in ogni pagina, utilizza un
GetQueryResults
e imposta il parametro
Opzione pageSize
dell'oggettoQueryResultsOption
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 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 ulteriori informazioni, vedi Configura 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. - Ottieni lo schema della tabella con
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 per la configurazione di Python nel Guida rapida di BigQuery con librerie client. 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.