Questa pagina mostra come eseguire query sui dati archiviati in BigQuery dall'interfaccia JupyterLab dell'istanza di Gemini Enterprise Agent Platform Workbench.
Metodi per eseguire query sui dati BigQuery nei file di blocchi note (IPYNB)
Per eseguire query sui dati BigQuery da un file di blocchi note JupyterLab, puoi utilizzare il comando magico %%bigquery e la libreria client BigQuery per Python.
Le istanze di Agent Platform Workbench includono anche un'integrazione BigQuery che ti consente di sfogliare ed eseguire query sui dati dall'interfaccia JupyterLab.
Questa pagina descrive come utilizzare ciascuno di questi metodi.
Prima di iniziare
Se non l'hai già fatto, crea un'istanza di Agent Platform Workbench.
Ruoli obbligatori
Per assicurarti che il account di servizio dell'istanza disponga delle autorizzazioni necessarie per eseguire query sui dati in BigQuery, chiedi all'amministratore di concedere il ruolo IAM Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) al account di servizio dell'istanza nel progetto.
L'amministratore potrebbe anche assegnare al account di servizio dell'istanza le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.
Apri JupyterLab
Nella Google Cloud console, vai alla pagina Istanze.
Fai clic su Apri JupyterLab accanto al nome dell'istanza di Agent Platform Workbench.
L'istanza di Agent Platform Workbench apre JupyterLab.
Sfoglia le risorse BigQuery
L'integrazione BigQuery fornisce un riquadro per sfogliare le risorse BigQuery a cui hai accesso.
Nel menu di navigazione di JupyterLab, fai clic su
BigQuery nei blocchi note.Il riquadro BigQuery elenca i progetti e i set di dati disponibili, in cui puoi eseguire le seguenti attività:
- Per visualizzare una descrizione di un set di dati, fai doppio clic sul nome del set di dati.
- Per mostrare le tabelle, le viste e i modelli di un set di dati, espandi il set di dati.
- Per aprire una descrizione di riepilogo come scheda in JupyterLab, fai doppio clic su una tabella, una vista o un modello.
Nota:nella descrizione di riepilogo di una tabella, fai clic sulla scheda Anteprima per visualizzare l'anteprima dei dati di una tabella. L'immagine seguente mostra un'anteprima della
international_top_termstabella che si trova nelgoogle_trendsset di dati nelbigquery-public-dataprogetto:
Esegui query sui dati utilizzando il comando magico %%bigquery
In questa sezione scriverai SQL direttamente nelle celle dei blocchi note e leggerai i dati da BigQuery nel blocco note Python.
I comandi magici che utilizzano un singolo o doppio carattere percentuale (% o %%)
consentono di utilizzare una sintassi minima per interagire con BigQuery all'interno del
blocco note. La libreria client BigQuery per Python viene installata automaticamente in un'istanza di Agent Platform Workbench. Dietro le quinte, il comando magico %%bigquery utilizza la libreria client BigQuery per Python per eseguire la query specificata, convertire i risultati in un DataFrame pandas, salvare facoltativamente i risultati in una variabile e quindi visualizzarli.
Nota: a partire dalla versione 1.26.0 del pacchetto Python google-cloud-bigquery,
l'API BigQuery Storage
viene utilizzata per impostazione predefinita per scaricare i risultati dai comandi magici %%bigquery.
Per aprire un file di blocchi note, seleziona File > Nuovo > Blocco note.
Nella finestra di dialogo Seleziona kernel , seleziona Python 3 e poi fai clic su Seleziona.
Viene aperto il nuovo file IPYNB.
Per ottenere il numero di regioni per paese nel set di dati
international_top_terms, inserisci la seguente istruzione:%%bigquery SELECT country_code, country_name, COUNT(DISTINCT region_code) AS num_regions FROM `bigquery-public-data.google_trends.international_top_terms` WHERE refresh_date = DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY) GROUP BY country_code, country_name ORDER BY num_regions DESC;
Fai clic su Esegui cella.
L'output è simile al seguente:
Query complete after 0.07s: 100%|██████████| 4/4 [00:00<00:00, 1440.60query/s] Downloading: 100%|██████████| 41/41 [00:02<00:00, 20.21rows/s] country_code country_name num_regions 0 TR Turkey 81 1 TH Thailand 77 2 VN Vietnam 63 3 JP Japan 47 4 RO Romania 42 5 NG Nigeria 37 6 IN India 36 7 ID Indonesia 34 8 CO Colombia 33 9 MX Mexico 32 10 BR Brazil 27 11 EG Egypt 27 12 UA Ukraine 27 13 CH Switzerland 26 14 AR Argentina 24 15 FR France 22 16 SE Sweden 21 17 HU Hungary 20 18 IT Italy 20 19 PT Portugal 20 20 NO Norway 19 21 FI Finland 18 22 NZ New Zealand 17 23 PH Philippines 17 ...
Nella cella successiva (sotto l'output della cella precedente), inserisci il seguente comando per eseguire la stessa query, ma questa volta salva i risultati in un nuovo DataFrame pandas denominato
regions_by_country. Puoi fornire questo nome utilizzando un argomento con il comando magico%%bigquery.%%bigquery regions_by_country SELECT country_code, country_name, COUNT(DISTINCT region_code) AS num_regions FROM `bigquery-public-data.google_trends.international_top_terms` WHERE refresh_date = DATE_SUB(CURRENT_DATE, INTERVAL 1 DAY) GROUP BY country_code, country_name ORDER BY num_regions DESC;
Nota:per saperne di più sugli argomenti disponibili per il
%%bigquerycomando, consulta la documentazione dei comandi magici della libreria client.Fai clic su Esegui cella.
Nella cella successiva, inserisci il seguente comando per esaminare le prime righe dei risultati della query appena letti:
regions_by_country.head()Fai clic su Esegui cella.
Il DataFrame pandas
regions_by_countryè pronto per essere tracciato.
Esegui query sui dati utilizzando direttamente la libreria client BigQuery
In questa sezione utilizzerai direttamente la libreria client BigQuery per Python per leggere i dati nel blocco note Python.
La libreria client ti offre un maggiore controllo sulle query e ti consente di utilizzare configurazioni più complesse per query e job. Le integrazioni della libreria con pandas ti consentono di combinare la potenza di SQL dichiarativo con codice imperativo (Python) per analizzare, visualizzare e trasformare i dati.
Nota:puoi utilizzare una serie di librerie Python per l'analisi, il data wrangling e la visualizzazione dei dati, come numpy, pandas, matplotlib e molte altre. Molte di queste librerie si basano su un oggetto DataFrame.
Nella cella successiva, inserisci il seguente codice Python per importare la libreria client BigQuery per Python e inizializzare un client:
from google.cloud import bigquery client = bigquery.Client()Il client BigQuery viene utilizzato per inviare e ricevere messaggi dall'API BigQuery.
Fai clic su Esegui cella.
Nella cella successiva, inserisci il seguente codice per recuperare la percentuale dei termini principali giornalieri negli Stati Uniti
top_termsche si sovrappongono nel tempo in base al numero di giorni di distanza. L'idea è di esaminare i termini principali di ogni giorno e vedere la percentuale di sovrapposizione con i termini principali del giorno precedente, di 2 giorni prima, di 3 giorni prima e così via (per tutte le coppie di date in un periodo di circa un mese).sql = """ WITH TopTermsByDate AS ( SELECT DISTINCT refresh_date AS date, term FROM `bigquery-public-data.google_trends.top_terms` ), DistinctDates AS ( SELECT DISTINCT date FROM TopTermsByDate ) SELECT DATE_DIFF(Dates2.date, Date1Terms.date, DAY) AS days_apart, COUNT(DISTINCT (Dates2.date || Date1Terms.date)) AS num_date_pairs, COUNT(Date1Terms.term) AS num_date1_terms, SUM(IF(Date2Terms.term IS NOT NULL, 1, 0)) AS overlap_terms, SAFE_DIVIDE( SUM(IF(Date2Terms.term IS NOT NULL, 1, 0)), COUNT(Date1Terms.term) ) AS pct_overlap_terms FROM TopTermsByDate AS Date1Terms CROSS JOIN DistinctDates AS Dates2 LEFT JOIN TopTermsByDate AS Date2Terms ON Dates2.date = Date2Terms.date AND Date1Terms.term = Date2Terms.term WHERE Date1Terms.date <= Dates2.date GROUP BY days_apart ORDER BY days_apart; """ pct_overlap_terms_by_days_apart = client.query(sql).to_dataframe() pct_overlap_terms_by_days_apart.head()
L'SQL utilizzato è incapsulato in una stringa Python e poi passato al
query()metodo per eseguire una query. Ilto_dataframemetodo attende il completamento della query e scarica i risultati in un DataFrame pandas utilizzando l'API BigQuery Storage.Fai clic su Esegui cella.
Le prime righe dei risultati della query vengono visualizzate sotto la cella di codice.
days_apart num_date_pairs num_date1_terms overlap_terms pct_overlap_terms 0 0 32 800 800 1.000000 1 1 31 775 203 0.261935 2 2 30 750 73 0.097333 3 3 29 725 31 0.042759 4 4 28 700 23 0.032857
Per saperne di più sull'utilizzo delle librerie client BigQuery, consulta la guida rapida Utilizzo delle librerie client.
Esegui query sui dati utilizzando l'integrazione BigQuery in Agent Platform Workbench
L'integrazione BigQuery fornisce due metodi aggiuntivi per eseguire query sui dati. Questi metodi sono diversi dall'utilizzo del comando magico %%bigquery.
L'editor di query in-cell è un tipo di cella che puoi utilizzare all'interno dei file di blocchi note.
L'editor di query autonomo si apre come scheda separata in JupyterLab.
In-cell
Per utilizzare l'editor di query in-cell per eseguire query sui dati in una tabella BigQuery:
In JupyterLab, apri un file di blocchi note (IPYNB) o creane uno nuovo.
Per creare un editor di query in-cell, fai clic sulla cella, e poi, a destra della cella, fai clic sul pulsante Integrazione BigQuery. In alternativa, in una cella Markdown, inserisci
#@BigQuery.L'integrazione BigQuery converte la cella in un editor di query in-cell.
In una nuova riga sotto
#@BigQuery, scrivi la query utilizzando le istruzioni e i dialetti SQL supportati di BigQuery. Se vengono rilevati errori nella query, viene visualizzato un messaggio di errore nell'angolo in alto a destra dell'editor di query. Se la query è valida, viene visualizzato il numero stimato di byte da elaborare.Fai clic su Invia query. Vengono visualizzati i risultati della query. Per impostazione predefinita, i risultati delle query vengono paginati a 100 righe per pagina e limitati a 1000 righe in totale, ma puoi modificare queste impostazioni nella parte inferiore della tabella dei risultati. Nell'editor di query, limita la query solo ai dati necessari per verificarla. Eseguirai di nuovo questa query in una cella del blocco note, dove potrai modificare il limite per recuperare l'intero set di risultati, se vuoi.
Puoi fare clic su Esegui query e carica come DataFrame per aggiungere automaticamente una nuova cella contenente un segmento di codice che importa la libreria client BigQuery per Python, esegue la query in una cella del blocco note e archivia i risultati in un DataFrame pandas denominato
df.
Autonomo
Per utilizzare l'editor di query autonomo per eseguire query sui dati in una tabella BigQuery:
In JupyterLab, nel riquadro BigQuery nei blocchi note , fai clic con il tasto destro del mouse su una tabella e seleziona Esegui query sulla tabella, oppure fai doppio clic su una tabella per aprire una descrizione in una scheda separata e poi fai clic sul link Esegui query sulla tabella.
Scrivi la query utilizzando le istruzioni e i dialetti SQL supportati di BigQuery. Se vengono rilevati errori nella query, viene visualizzato un messaggio di errore nell'angolo in alto a destra dell'editor di query. Se la query è valida, viene visualizzato il numero stimato di byte da elaborare.
Fai clic su Invia query. Vengono visualizzati i risultati della query. Per impostazione predefinita, i risultati delle query vengono paginati a 100 righe per pagina e limitati a 1000 righe in totale, ma puoi modificare queste impostazioni nella parte inferiore della tabella dei risultati. Nell'editor di query, limita la query solo ai dati necessari per verificarla. Eseguirai di nuovo questa query in una cella del blocco note, dove potrai modificare il limite per recuperare l'intero set di risultati, se vuoi.
Puoi fare clic su Copia codice per DataFrame per copiare un segmento di codice che importa la libreria client BigQuery per Python, esegue la query in una cella del blocco note e archivia i risultati in un DataFrame pandas denominato
df. Incolla questo codice in una cella del blocco note in cui vuoi eseguirlo.
Visualizza la cronologia delle query e riutilizza le query
Per visualizzare la cronologia delle query come scheda in JupyterLab:
Nel menu di navigazione di JupyterLab, fai clic su
BigQuery nei blocchi note per aprire il riquadro
BigQuery.Nel riquadro BigQuery, scorri verso il basso e fai clic su Cronologia query.
Si apre un elenco delle query in una nuova scheda, in cui puoi eseguire attività come le seguenti:
- Per visualizzare i dettagli di una query, come l'ID job, la data di esecuzione e la durata, fai clic sulla query.
- Per rivedere la query, eseguirla di nuovo o copiarla nel blocco note per un utilizzo futuro, fai clic su Apri query nell'editor.
Passaggi successivi
Per vedere esempi di come visualizzare i dati delle tabelle BigQuery, consulta Esplora e visualizza i dati in BigQuery da JupyterLab.
Per saperne di più sulla scrittura di query per BigQuery, consulta Esecuzione di job di query interattivi e batch.
Scopri come controllare l'accesso ai set di dati BigQuery.
Scopri come accedere ai bucket e ai file Cloud Storage da JupyterLab.