Como migrar do pacote datalab do Python

O pacote datalab do Python é usado para interagir com os serviços do Google Cloud por meio dos notebooks do Datalab. O pacote datalab do Python inclui mágicas do Jupyter e módulos do 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 Python oficial 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 seguintes exemplos de código ilustram como executar operações comuns do BigQuery usando a biblioteca google-cloud-bigquery para desenvolvedores que já estão familiarizados com o pacote datalab do Python.

Consulte o requirements.txt.file 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 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 os métodos da ferramenta de linha de comando ou 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 após a instalação do 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. Os pacotes datalab e google-cloud-python do Python implementam comandos de mágica complementares que podem ser carregados nos notebooks do Jupyter (inclusive o Datalab) para interagir com o Google Cloud.

datalab

Os comandos mágicos datalab são pré-carregados nos notebooks do 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 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: o %load_ext é um dos muitos comandos mágicos integrados do Jupyter. Consulte a documentação do Jupyter para mais informações sobre %load_ext e outros comandos mágicos incorporados.

O comando mágico de célula do BigQuery funcionará em qualquer notebook em que o pacote google-cloud-bigquery esteja 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, a consulta é executada e os resultados 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 panda.

%%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, você verá como executar uma consulta e como armazenar os resultados em uma variável chamada my_variable.

datalab

O comando mágico de consulta 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

Então, é possível executar a consulta salva 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 o 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 complementares

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 bq. Nos exemplos a seguir, você verá como listar todas as tabelas no conjunto de dados do samples do projeto bigquery-public-data usando um comando mágico de célula do datalab ou um comando de shell do BigQuery.

datalab

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

Ferramenta de linha de comando bq

Para começar a usar a ferramenta de linha de comando bq, 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 bq estiver configurada e 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 é um comando de shell em vez de mágica. 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: há ferramentas de linha de comando para muitos serviços do Google Cloud, como gsutil, que fornecem uma interface apropriada para comandos mágicos que pode ser usada em notebooks ou na linha de comando.

Como usar o código Python

Além dos comandos mágicos do Jupyter, também é possível executar 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 de uso da biblioteca de cliente Python do BigQuery, consulte Como carregar dados em lote 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 de 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 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 (e isso é diferente de uma inserção de streaming). Os dados ficam imediatamente disponíveis após a conclusão do job de carregamento.

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