Utilizzare l'impaginazione con l'API BigQuery
Questo documento descrive come leggere i dati delle tabelle e i risultati delle query in set di dati di grandi dimensioni utilizzando l'impaginazione con l'API BigQuery.
Con l'impaginazione, BigQuery suddivide un set di dati di grandi dimensioni in blocchi più piccoli chiamati pagine. Per la maggior parte degli utenti, le librerie client di Cloud gestiscono automaticamente questo processo, ma puoi anche controllare manualmente l'impaginazione per casi d'uso specifici come le applicazioni web.
Utilizzare l'impaginazione automatica
Le librerie client di Cloud gestiscono i dettagli di basso livello dell'impaginazione dell'API e forniscono un'esperienza simile a un iteratore. Quando scorri i risultati, la libreria recupera automaticamente la pagina di dati successiva quando è necessario.
Gli esempi seguenti mostrano come scorrere automaticamente i 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 saperne di più, consulta la documentazione di riferimento dell'C# API BigQuery.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Vai
Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'Go API BigQuery.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Java BigQuery.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'Node.js API BigQuery.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
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 saperne di più, consulta la documentazione di riferimento dell' API PHP BigQuery.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
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 saperne di più, consulta la documentazione di riferimento dell'API PythonBigQuery.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
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 saperne di più, consulta la documentazione di riferimento dell'API Ruby BigQuery.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Controllare le dimensioni della pagina
Puoi specificare il numero massimo di righe restituite in ogni richiesta di rete impostando le dimensioni della pagina. L'impostazione delle dimensioni della pagina è utile per ottimizzare l'utilizzo della rete o per adattare i dati alla memoria.
Nella maggior parte delle librerie client, puoi utilizzare un parametro max_results o page_size quando chiami metodi come list_rows o query.
Utilizzare l'impaginazione manuale con i token di pagina
L'impaginazione manuale è utile per le applicazioni senza stato, come un servizio web in cui un utente fa clic su Avanti per visualizzare il set di risultati successivo. In questo scenario, il server non mantiene un iteratore attivo tra le richieste.
In alternativa, puoi utilizzare un token di pagina come segue:
- Richiedi una pagina. Chiama l'API e ricevi un parametro
pageTokeninsieme alle righe. - Riprendi. Nella richiesta successiva, ritrasmetti lo stesso parametro
pageTokena BigQuery per recuperare il blocco di dati successivo.
Gli esempi seguenti mostrano come recuperare un token di pagina e utilizzarlo per recuperare la pagina successiva dei risultati della query.
API
Leggi il
jobs.config.query.destinationTable
campo 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 di configurazione Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Java BigQuery.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Per impostare il numero di righe restituite in ogni pagina, utilizza un
GetQueryResults job e imposta l'
pageSize opzione
dell'QueryResultsOption oggetto 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 di configurazione Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'Node.js API BigQuery.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Python
Il
QueryJob.result
metodo restituisce un iterabile dei risultati della query. In alternativa,
- Leggi la
QueryJob.destinationproprietà. Se questa proprietà non è configurata, l'API la imposta su un riferimento a una tabella anonima temporanea. - Recupera lo schema della tabella con il
Client.get_tablemetodo. - Crea un iterabile su tutte le righe della tabella di destinazione con il
Client.list_rowsmetodo.
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API PythonBigQuery.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Ottimizzare con gli ETag
Quando torni indietro o vai a pagine arbitrarie utilizzando i valori pageToken memorizzati nella cache, è possibile che i dati nelle pagine siano stati modificati dall'ultima volta che sono stati visualizzati. Per attenuare questo risultato, 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 effettui 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 dei valori ETag. Puoi utilizzare gli ETag per evitare chiamate di elenco ridondanti come segue:
- Per restituire i valori solo se sono stati modificati, effettua una chiamata di elenco con un
ETag memorizzato in precedenza utilizzando l'
intestazione
If-None-MatchHTTP. Se gli ETag corrispondono, BigQuery restituisce un codice di statoHTTP 304 Not Modifiede nessun dato, risparmiando larghezza di banda. - Per restituire i valori solo se non sono stati modificati, utilizza l'
intestazione
If-MatchHTTP. BigQuery restituisce un412 Precondition Failedse la pagina è stata modificata.
Riferimento: limiti e criteri dell'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 | Limite maxResults predefinito |
Limite maxResults massimo |
Limite maxFieldValues massimo |
|---|---|---|---|---|
tabledata.list |
Restituisce risultati impaginati se le dimensioni della risposta sono superiori a
10 MB1 di dati o a maxResults
righe. |
Illimitat | Illimitato | Illimitat |
Tutti gli altri metodi *collection*.list |
Restituisce risultati impaginati se la risposta è superiore a
maxResults righe e inferiore ai limiti massimi. |
10.000 | Illimitat | 300.000 |
Se il risultato supera il limite di byte o campi, viene troncato per rientrare nel limite. Se una riga supera il limite di byte o campi,
il metodo tabledata.list può restituire fino a 100 MB di dati1,
il che è coerente 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.
Il metodo dell'API REST jobs.getQueryResults può restituire 20 MB di dati, a meno che tu non ne richieda esplicitamente di più tramite l'assistenza.
1La dimensione della riga è approssimativa, poiché la dimensione 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 esecuzione.