Consultar dados no BigQuery a partir do JupyterLab

Consultar dados no BigQuery a partir do JupyterLab

Os blocos de notas geridos do Vertex AI Workbench foram descontinuados. A 14 de abril de 2025, o apoio técnico dos blocos de notas geridos terminou e a capacidade de criar instâncias de blocos de notas geridos foi removida. As instâncias existentes vão continuar a funcionar até 30 de março de 2026, mas os patches, as atualizações e as atualizações não vão estar disponíveis. Para continuar a usar o Vertex AI Workbench, recomendamos que migre as suas instâncias de notebooks geridos para instâncias do Vertex AI Workbench.

Esta página mostra como consultar dados armazenados no BigQuery a partir da interface do JupyterLab da instância de blocos de notas geridos do Vertex AI Workbench.

Métodos para consultar dados do BigQuery em ficheiros de bloco de notas (IPYNB)

Para consultar dados do BigQuery a partir de um ficheiro de bloco de notas do JupyterLab, pode usar o comando mágico %%bigquery e a biblioteca cliente do BigQuery para Python.

As instâncias de blocos de notas geridos também incluem uma integração do BigQuery que lhe permite procurar e consultar dados a partir da interface do JupyterLab.

Esta página descreve como usar cada um destes métodos.

Antes de começar

Se ainda não o fez, crie uma instância de blocos de notas geridos.

Abra o JupyterLab

1. Na Google Cloud consola, aceda à página Blocos de notas geridos.

   Aceda a notebooks geridos

2. Junto ao nome da instância de blocos de notas geridos, clique em Abrir JupyterLab.

   A sua instância de blocos de notas geridos abre o JupyterLab.

Procure recursos do BigQuery

A integração do BigQuery oferece um painel para procurar os recursos do BigQuery aos quais tem acesso.

1. No menu de navegação do JupyterLab, clique em  BigQuery in Notebooks.

   O painel BigQuery apresenta os projetos e os conjuntos de dados disponíveis, onde pode realizar tarefas da seguinte forma:

   • Para ver uma descrição de um conjunto de dados, clique duas vezes no nome do conjunto de dados.
   • Para mostrar as tabelas, as vistas e os modelos de um conjunto de dados, expanda o conjunto de dados.
   • Para abrir uma descrição de resumo como um separador no JupyterLab, clique duas vezes numa tabela, numa vista ou num modelo.

   Nota: na descrição do resumo de uma tabela, clique no separador Pré-visualizar para pré-visualizar os dados de uma tabela. A imagem seguinte mostra uma pré-visualização da tabela international_top_terms encontrada no conjunto de dados google_trends no projeto bigquery-public-data:

   

Consulte dados através do comando mágico %%bigquery

Nesta secção, escreve SQL diretamente nas células do bloco de notas e lê dados do BigQuery para o bloco de notas do Python.

Os comandos mágicos que usam um caráter de percentagem único ou duplo (% ou %%) permitem-lhe usar uma sintaxe mínima para interagir com o BigQuery no bloco de notas. A biblioteca cliente do BigQuery para Python é instalada automaticamente numa instância de blocos de notas geridos. Nos bastidores, o comando mágico %%bigquery usa a biblioteca cliente do BigQuery para Python para executar a consulta fornecida, converter os resultados num pandas DataFrame, opcionalmente guardar os resultados numa variável e, em seguida, apresentar os resultados.

Nota: a partir da versão 1.26.0 do pacote Python google-cloud-bigquery, a API BigQuery Storage é usada por predefinição para transferir resultados dos comandos mágicos %%bigquery.

1. Para abrir um ficheiro de bloco de notas, selecione Ficheiro > Novo > Bloco de notas.

2. Na caixa de diálogo Selecionar kernel, selecione Python (local) e, de seguida, clique em Selecionar.

   O novo ficheiro IPYNB é aberto.

3. Para obter o número de regiões por país no conjunto de dados international_top_terms, introduza a seguinte declaração:

   %%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;

4. Clique em  Executar célula.

   O resultado é semelhante ao seguinte:

   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
   ...
   

   Nota: os seus resultados podem diferir dos apresentados acima, uma vez que o google_trends conjunto de dados consultado é atualizado continuamente com novos dados.

5. Na célula seguinte (abaixo da saída da célula anterior), introduza o comando seguinte para executar a mesma consulta, mas desta vez guarde os resultados num novo DataFrame pandas denominado regions_by_country. Fornece esse nome através de um argumento com o comando mágico %%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: para mais informações sobre os argumentos disponíveis para o comando %%bigquery, consulte a documentação de comandos mágicos da biblioteca de cliente.

6. Clique em  Executar célula.

7. Na célula seguinte, introduza o seguinte comando para ver as primeiras linhas dos resultados da consulta que acabou de ler:

   regions_by_country.head()
   

8. Clique em  Executar célula.

   O pandas DataFrame regions_by_country está pronto para ser representado graficamente.

Consultar dados através da biblioteca cliente do BigQuery diretamente

Nesta secção, usa a biblioteca cliente do BigQuery para Python diretamente para ler dados no bloco de notas Python.

A biblioteca de cliente dá-lhe mais controlo sobre as suas consultas e permite-lhe usar configurações mais complexas para consultas e tarefas. As integrações da biblioteca com o pandas permitem-lhe combinar o poder do SQL declarativo com o código imperativo (Python) para ajudar a analisar, visualizar e transformar os seus dados.

Nota: pode usar várias bibliotecas de análise de dados, organização de dados e visualização do Python, como numpy, pandas, matplotlib e muitas outras. Várias destas bibliotecas são criadas com base num objeto DataFrame.

1. Na célula seguinte, introduza o seguinte código Python para importar a biblioteca cliente do BigQuery para Python e inicializar um cliente:

   from google.cloud import bigquery
   
   client = bigquery.Client()
   

   O cliente do BigQuery é usado para enviar e receber mensagens da API BigQuery.

2. Clique em  Executar célula.

3. Na célula seguinte, introduza o seguinte código para obter a percentagem dos principais termos diários nos EUA top_terms que se sobrepõem ao longo do tempo por número de dias de diferença. A ideia aqui é analisar os principais termos de cada dia e ver a percentagem dos mesmos que se sobrepõem aos principais termos do dia anterior, 2 dias antes, 3 dias antes e assim sucessivamente (para todos os pares de datas num período de cerca de um mês).

   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()

   O SQL usado está encapsulado numa string Python e, em seguida, é transmitido ao método query() para executar uma consulta. O método to_dataframe aguarda a conclusão da consulta e transfere os resultados para um pandas DataFrame através da API BigQuery Storage.

4. Clique em  Executar célula.

   As primeiras linhas dos resultados da consulta aparecem abaixo da célula de código.

      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
   

   Nota: os seus resultados podem diferir dos apresentados acima, uma vez que o google_trends conjunto de dados consultado é atualizado continuamente com novos dados.

Para mais informações sobre a utilização de bibliotecas cliente do BigQuery, consulte o início rápido Usar bibliotecas cliente.

Consulte dados através da integração do BigQuery em blocos de notas geridos

A integração do BigQuery oferece dois métodos adicionais para consultar dados. Estes métodos são diferentes da utilização do comando mágico %%bigquery.

• O editor de consultas na célula é um tipo de célula que pode usar nos seus ficheiros de bloco de notas.

• O editor de consultas autónomo é aberto como um separador separado no JupyterLab.

In-cell

Para usar o editor de consultas na célula para consultar dados numa tabela do BigQuery, conclua os seguintes passos:

1. No JupyterLab, abra um ficheiro de notebook (IPYNB) ou crie um novo.

2. Para criar um editor de consultas na célula, clique na célula e, de seguida, à direita da célula, clique no botão  Integração do BigQuery. Em alternativa, numa célula de markdown, introduza #@BigQuery.

   A integração do BigQuery converte a célula num editor de consultas na célula.

3. Numa nova linha abaixo de #@BigQuery, escreva a sua consulta usando as declarações e os dialetos de SQL suportados do BigQuery. Se forem detetados erros na sua consulta, é apresentada uma mensagem de erro no canto superior direito do editor de consultas. Se a consulta for válida, é apresentado o número estimado de bytes a serem processados.

4. Clique em Enviar consulta. Os resultados da consulta são apresentados. Por predefinição, os resultados da consulta são paginados a 100 linhas por página e limitados a um total de 1000 linhas, mas pode alterar estas definições na parte inferior da tabela de resultados. No editor de consultas, mantenha a consulta limitada apenas aos dados de que precisa para validar a consulta. Execute novamente esta consulta numa célula do bloco de notas, onde pode ajustar o limite para obter o conjunto de resultados completo, se quiser.

   Nota: o texto da consulta e os resultados persistem depois de fechar e reabrir o ficheiro do bloco de notas.

5. Pode clicar em Consultar e carregar como DataFrame para adicionar automaticamente uma nova célula que contém um segmento de código que importa a biblioteca do cliente do BigQuery para Python, executa a sua consulta numa célula do bloco de notas e armazena os resultados num dataframe pandas denominado df.

Autónomo

Para usar o editor de consultas autónomo para consultar dados numa tabela do BigQuery, conclua os seguintes passos:

1. No JupyterLab, no painel BigQuery in Notebooks, clique com o botão direito do rato numa tabela e selecione Consultar tabela ou clique duas vezes numa tabela para abrir uma descrição num separador separado e, de seguida, clique no link Consultar tabela.

2. Escreva a sua consulta usando as declarações e os dialetos de SQL suportados do BigQuery. Se forem detetados erros na sua consulta, é apresentada uma mensagem de erro no canto superior direito do editor de consultas. Se a consulta for válida, é apresentado o número estimado de bytes a serem processados.

3. Clique em Enviar consulta. Os resultados da consulta são apresentados. Por predefinição, os resultados da consulta são paginados a 100 linhas por página e limitados a um total de 1000 linhas, mas pode alterar estas definições na parte inferior da tabela de resultados. No editor de consultas, mantenha a consulta limitada apenas aos dados de que precisa para validar a consulta. Execute novamente esta consulta numa célula do bloco de notas, onde pode ajustar o limite para obter o conjunto de resultados completo, se quiser.

4. Pode clicar em Copiar código para DataFrame para copiar um segmento de código que importa a biblioteca do cliente do BigQuery para Python, executa a sua consulta numa célula do bloco de notas e armazena os resultados num dataframe pandas denominado df. Cole este código numa célula do bloco de notas onde o quer executar.

Veja o histórico de consultas e reutilize consultas

Para ver o seu histórico de consultas como um separador no JupyterLab, siga estes passos:

1. No menu de navegação do JupyterLab, clique em  BigQuery nos blocos de notas para abrir o painel BigQuery.

2. No painel BigQuery, desloque a página para baixo e clique em Histórico de consultas.

   

   É aberta uma lista das suas consultas num novo separador, onde pode realizar tarefas como as seguintes:

   • Para ver os detalhes de uma consulta, como o ID da tarefa, quando a consulta foi executada e quanto tempo demorou, clique na consulta.
   • Para rever a consulta, executá-la novamente ou copiá-la para o seu bloco de notas para utilização futura, clique em Abrir consulta no editor.

Nota: se executar consultas depois de abrir este separador, clique em  Atualizar para mostrar as consultas mais recentes.

O que se segue?

• Para ver exemplos de como visualizar os dados das suas tabelas do BigQuery, consulte o artigo Explorar e visualizar dados no BigQuery a partir do JupyterLab.

• Para saber como escrever consultas para o BigQuery, consulte o artigo Executar tarefas de consultas interativas e em lote.

• Saiba como controlar o acesso aos conjuntos de dados do BigQuery.

• Saiba como aceder a contentores e ficheiros do Cloud Storage a partir do JupyterLab.