O pacote Python datalab
é usado para interagir com os serviços do Google Cloud Platform por meio de notebooks do Cloud Datalab. O pacote datalab
inclui comandos mágicos Jupyter e módulos Python como google.datalab.bigquery
, que são compatíveis com um subconjunto dos métodos da API BigQuery.
A biblioteca de cliente do BigQuery, google-cloud-bigquery
, é a biblioteca oficial Python usada para interagir com o BigQuery. Ela fornece um comando mágico de célula Jupyter para executar consultas e funções que permitem enviar e recuperar dados por meio de DataFrames pandas. Além disso, a biblioteca é compatível com a funcionalidade completa do BigQuery. Os exemplos de código a seguir ilustram como é possível realizar operações comuns do BigQuery usando a biblioteca google-cloud-bigquery
para desenvolvedores que já estão familiarizados com o pacote Python datalab
.
Consulte o requirements.txt.file (em inglês) para as versões das bibliotecas usadas nestes snippets de código.
Como usar os comandos do shell e os comandos mágicos do Jupyter
Ambas as bibliotecas aceitam a consulta de dados armazenados no BigQuery com um comando mágico de célula. As principais diferenças nas abordagens das duas bibliotecas com relação aos comandos mágicos incluem o seguinte:
datalab |
google-cloud-bigquery |
|
---|---|---|
Nome do comando mágico | bq |
bigquery |
Nome da extensão do Jupyter, usada para carregar os comandos mágicos | google.datalab.kernel |
google.cloud.bigquery |
Execução da consulta | A definição e a execução da consulta podem ser executadas em etapas separadas. | A consulta é sempre realizada imediatamente quando o comando mágico é executado. |
Funcionalidade dos comandos mágicos | Alguns recursos não são compatíveis. | É possível executar somente consultas por meio dos comandos mágicos. Para outras funcionalidades do BigQuery, use a ferramenta de linha de comando ou os métodos google.cloud.bigquery.Client. |
Como salvar resultados da consulta | É possível salvar os resultados em uma tabela de destino por meio do comando mágico de consulta. No entanto, eles não podem ser salvos em uma variável. Para salvar os resultados em uma variável, execute a consulta usando o Python em vez dos comandos mágicos. Veja o exemplo. | É possível salvar os resultados em uma variável por meio dos comandos mágicos de consulta. No entanto, eles não podem ser salvos em uma tabela de destino. Para salvar os resultados em uma tabela de destino, execute a consulta usando o Python em vez dos comandos mágicos. Veja o exemplo. |
Como instalar a biblioteca de cliente do Python
Para instalar a biblioteca de cliente do BigQuery com as dependências necessárias para trabalhar com DataFrames pandas, insira o seguinte comando no notebook:
!pip install --upgrade google-cloud-bigquery[pandas,pyarrow]
Como carregar comandos mágicos
Os comandos mágicos Jupyter são atalhos específicos de notebook para executar comandos com sintaxe mínima. Os notebooks do Jupyter incluem muitos comandos integrados pré-carregados.
Com os pacotes Python datalab
e google-cloud-python
, você implementa comandos mágicos extras que podem ser carregados nos notebooks do Jupyter, incluindo o Cloud Datalab. Assim, é possível interagir com o Google Cloud Platform.
datalab
Os comandos mágicos do datalab
são pré-carregados nos notebooks do Cloud Datalab. Para carregá-los em um notebook do Jupyter, insira o seguinte comando:
%load_ext google.datalab.kernel
Veja mais opções para carregar comandos mágicos no repositório de origem (em inglês) da biblioteca datalab
.
google-cloud-bigquery
Para carregar o comando mágico do BigQuery, insira o comando a seguir:
%load_ext google.cloud.bigquery
O comando mágico de célula do BigQuery funciona em qualquer notebook que tenha o pacote google-cloud-bigquery
instalado. Para usar o comando mágico de célula, você precisa utilizar a versão 0.32.0 ou superior da biblioteca de cliente.
Como executar consultas
Nos exemplos a seguir, veja como usar um comando mágico de célula para executar uma consulta. Em ambos os exemplos, os resultados das consultas são exibidos abaixo da célula de entrada.
datalab
google-cloud-bigquery
Como executar uma consulta e armazenar os resultados em uma variável
No exemplo a seguir, veja como executar uma consulta e armazenar os resultados em uma variável denominada my_variable
.
datalab
datalab
salva uma consulta SQL sem executá-la ao passar um nome com as sinalizações --name
ou -n
.
google-cloud-bigquery
Como executar uma consulta parametrizada
No exemplo a seguir, veja como executar uma consulta parametrizada. Com ela, é possível definir parâmetros de consulta e executar a consulta em células separadas. Consulte Como executar consultas parametrizadas para mais informações.
datalab
google-cloud-bigquery
Comandos extras
A biblioteca datalab
contém comandos mágicos para muitos tipos de operações do BigQuery. Já a biblioteca google-cloud-bigquery
conta com um comando mágico de célula para executar consultas. Para executar os comandos de outras opções além da consulta, use a ferramenta de linha de comando do BigQuery. Nos exemplos a seguir, veja como listar todas as tabelas no conjunto de dados samples
do projeto bigquery-public-data
usando um comando mágico de célula do datalab
ou um comando do shell do BigQuery.
datalab
Ferramenta de linha de comando do BigQuery
Para começar a usar a ferramenta de linha de comando do BigQuery, que é instalada como parte do SDK do Cloud, siga as instruções de instalação do SDK do Cloud.
Os comandos do shell em um notebook precisam ter !
como prefixo. Quando a ferramenta de linha de comando do BigQuery for configurada e ficar disponível no notebook, insira o comando a seguir. Ele equivale ao comando mágico de célula datalab
acima.
!bq ls bigquery-public-data:samples
Para uma lista completa de comandos, insira o comando a seguir:
!bq help
Como usar o código Python
Além dos comandos mágicos Jupyter, também é possível realizar operações do BigQuery usando métodos Python nos pacotes datalab
e google-cloud-bigquery
.
Como executar uma consulta
Ambas as bibliotecas são compatíveis com a execução de consultas e retornam os resultados como um DataFrame pandas.
datalab
google-cloud-bigquery
Como carregar dados em uma tabela do BigQuery
No exemplo a seguir, veja como criar um novo conjunto de dados e carregar os dados de um arquivo CSV do Cloud Storage em uma nova tabela.
datalab
google-cloud-bigquery
Para mais exemplos sobre como usar a biblioteca de cliente Python do BigQuery, consulte Como carregar dados do Cloud Storage, Como carregar dados de uma origem local para o BigQuery e Como fazer streaming de dados para o BigQuery.
Como carregar um DataFrame do pandas para uma tabela do BigQuery
Veja no exemplo a seguir como criar um novo conjunto de dados e carregar os dados de um DataFrame pandas em uma nova tabela.
Os locais são obrigatórios em determinadas operações do BigQuery, como a criação de um conjunto de dados. Se um local for fornecido a um cliente de google-cloud-bigquery
quando inicializado, ele será o local padrão dos jobs, conjuntos de dados e tabelas criados com o cliente. A biblioteca datalab
não fornece uma forma de especificar os locais do job ou conjunto de dados, o que pode gerar comportamento inesperado. Consulte os Locais dos conjuntos de dados para mais informações.
datalab
datalab
executa uma inserção de streaming ao carregar dados de um DataFrame pandas em uma tabela do BigQuery. Por conta disso, os dados podem não ficar imediatamente disponíveis para as consultas. Consulte Como fazer o streaming de dados no BigQuery para mais informações.