Como migrar do pacote datalab do Python

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.

Observação: neste guia, datalab se refere ao pacote datalab do Python, e não ao serviço de notebook hospedado Cloud Datalab.

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]

Observação: pode ser necessário reiniciar o kernel depois de instalar o pacote.

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

Observação: %load_ext é um dos vários comandos mágicos integrados ao Jupyter. Consulte a documentação do Jupyter (em inglês) para mais informações sobre %load_ext e outros comandos mágicos integrados.

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

Os resultados da consulta são exibidos abaixo da célula de entrada como QueryResultsTable.

%%bq query
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
GROUP BY word
ORDER BY count ASC
LIMIT 100

google-cloud-bigquery

Os resultados da consulta são exibidos abaixo da célula de entrada em um DataFrame pandas.

%%bigquery
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
GROUP BY word
ORDER BY count ASC
LIMIT 100

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

O comando mágico de consulta do datalab salva uma consulta SQL sem executá-la ao passar um nome com as sinalizações --name ou -n.

%%bq query -n my_query
SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
WHERE state = "TX"
LIMIT 100

A consulta salva é executada separadamente, com os resultados armazenados em uma variável.

import google.datalab.bigquery as bq

my_variable = my_query.execute().result().to_dataframe()

google-cloud-bigquery

%%bigquery my_variable
SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
WHERE state = "TX"
LIMIT 100

Observação: para salvar os resultados em uma tabela de destino, execute a consulta usando o Python em vez dos comandos mágicos. Veja um exemplo.

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

Defina a consulta.

%%bq query -n my_query
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
WHERE corpus = @corpus_name
GROUP BY word
ORDER BY count ASC
LIMIT @limit

Defina os parâmetros.

corpus_name = "hamlet"
limit = 10

Execute a consulta.

%%bq execute -q my_query --to-dataframe
parameters:
- name: corpus_name
  type: STRING
  value: $corpus_name
- name: limit
  type: INTEGER
  value: $limit

google-cloud-bigquery

Defina os parâmetros.

params = {"corpus_name": "hamlet", "limit": 10}

Defina e execute a consulta.

%%bigquery --params $params
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
WHERE corpus = @corpus_name
GROUP BY word
ORDER BY count ASC
LIMIT @limit

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

%bq tables list --dataset bigquery-public-data.samples

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

Observação: o primeiro caractere do comando é ! em vez de % para indicar que é do shell, e não um comando mágico. Consulte os documentos do IPython para mais informações sobre como executar comandos do shell em um notebook.

Para uma lista completa de comandos, insira o comando a seguir:

!bq help

Observação: existem ferramentas de linha de comando para muitos serviços do Google Cloud Platform, como a gsutil, que oferecem uma interface mágica. Essa interface pode ser usada em notebooks ou na linha de comando.

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

Ver no GitHub Feedback

import google.datalab.bigquery as bq

sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = "TX"
    LIMIT 100
"""
df = bq.Query(sql).execute().result().to_dataframe()

google-cloud-bigquery

Ver no GitHub Feedback

from google.cloud import bigquery

client = bigquery.Client()
sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = "TX"
    LIMIT 100
"""
df = client.query(sql).to_dataframe()

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

Ver no GitHub Feedback

import google.datalab.bigquery as bq

# Create the dataset
dataset_id = 'import_sample'
bq.Dataset(dataset_id).create()

# Create the table
schema = [
    {'name': 'name', 'type': 'STRING'},
    {'name': 'post_abbr', 'type': 'STRING'},
]
table = bq.Table(
    '{}.us_states'.format(dataset_id)).create(schema=schema)
table.load(
    'gs://cloud-samples-data/bigquery/us-states/us-states.csv',
    mode='append',
    source_format='csv',
    csv_options=bq.CSVOptions(skip_leading_rows=1)
)  # Waits for the job to complete

google-cloud-bigquery

Ver no GitHub Feedback

from google.cloud import bigquery

client = bigquery.Client(location='US')

# Create the dataset
dataset_id = 'import_sample'
dataset = client.create_dataset(dataset_id)

# Create the table
job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField('name', 'STRING'),
        bigquery.SchemaField('post_abbr', 'STRING')
    ],
    skip_leading_rows=1,
    # The source format defaults to CSV, so the line below is optional.
    source_format=bigquery.SourceFormat.CSV
)
load_job = client.load_table_from_uri(
    'gs://cloud-samples-data/bigquery/us-states/us-states.csv',
    dataset.table('us_states'),
    job_config=job_config
)
load_job.result()  # Waits for table load to complete.

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

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

Ver no GitHub Feedback

import google.datalab.bigquery as bq
import pandas

# Create the dataset
dataset_id = 'import_sample'
bq.Dataset(dataset_id).create()

# Create the table and load the data
dataframe = pandas.DataFrame([
    {'title': 'The Meaning of Life', 'release_year': 1983},
    {'title': 'Monty Python and the Holy Grail', 'release_year': 1975},
    {'title': 'Life of Brian', 'release_year': 1979},
    {
        'title': 'And Now for Something Completely Different',
        'release_year': 1971
    },
])
schema = bq.Schema.from_data(dataframe)
table = bq.Table(
    '{}.monty_python'.format(dataset_id)).create(schema=schema)
table.insert(dataframe)  # Starts steaming insert of data

google-cloud-bigquery

A biblioteca de cliente do BigQuery converte o DataFrame pandas para o formato parquet e executa um job de carregamento. Isso é diferente de uma inserção de streaming. Os dados ficam imediatamente disponíveis após a conclusão do job de carregamento.

Ver no GitHub Feedback

from google.cloud import bigquery
import pandas

client = bigquery.Client(location='US')

dataset_id = 'import_sample'
dataset = client.create_dataset(dataset_id)

# Create the table and load the data
dataframe = pandas.DataFrame([
    {'title': 'The Meaning of Life', 'release_year': 1983},
    {'title': 'Monty Python and the Holy Grail', 'release_year': 1975},
    {'title': 'Life of Brian', 'release_year': 1979},
    {
        'title': 'And Now for Something Completely Different',
        'release_year': 1971
    },
])
table_ref = dataset.table('monty_python')
load_job = client.load_table_from_dataframe(dataframe, table_ref)
load_job.result()  # Waits for table load to complete.