Migrar desde el paquete de Datalab para Python

El paquete de Python datalab se usa para interactuar con los servicios de Google Cloud a través de los notebooks de Datalab. El paquete de Python datalab incluye módulos de Python y comandos mágicos de Jupyter, como google.datalab.bigquery, que admiten un subconjunto de los métodos de la API de BigQuery.

La biblioteca cliente de BigQuery, google-cloud-bigquery, es la biblioteca oficial de Python que se usa para interactuar con BigQuery. La biblioteca cliente proporciona un comando mágico de celda de Jupyter para ejecutar consultas, así como compatibilidad con todas las funciones de BigQuery y funciones que permiten enviar y recuperar datos mediante DataFrames de Pandas. En los siguientes ejemplos de código, se ilustra cómo realizar operaciones comunes de BigQuery con la biblioteca google-cloud-bigquery para desarrolladores que ya están saben usar el paquete de Python datalab.

Consulta el archivo requirements.txt para ver las versiones de las bibliotecas que se usan con estos fragmentos de código.

Nota: datalab en esta guía hace referencia al paquete de Python datalab, no al servicio de notebook alojado Datalab.

Usa comandos mágicos y de shell en Jupyter

Ambas bibliotecas admiten la consulta de datos almacenados en BigQuery con un comando mágico de celda. Las diferencias clave entre los enfoques que aplican estas dos bibliotecas en cuanto a los comandos mágicos incluyen lo siguiente:

	datalab	google-cloud-bigquery
Nombre del comando mágico	bq	bigquery
Nombre de la extensión de Jupyter (que se usa para cargar los comandos mágicos)	google.datalab.kernel	google.cloud.bigquery
Ejecución de las consultas	La definición y ejecución de una consulta se pueden realizar en pasos separados.	La consulta siempre se realiza inmediatamente cuando se ejecuta el comando mágico.
Funciones que abarcan los comandos mágicos	No se admiten algunas funciones.	Solo se pueden realizar consultas con los comandos mágicos. Para otras funciones de BigQuery, usa la herramienta de línea de comandos o los métodos google.cloud.bigquery.Client.
Guardar resultados de consultas	El comando mágico de una consulta permite guardar los resultados en una tabla de destino, pero no en una variable. Si deseas guardar los resultados de una consulta en una variable, ejecuta la consulta con Python en lugar de usar comandos mágicos (ver el ejemplo).	El comando mágico de consulta permite guardar los resultados en una variable, pero no en una tabla de destino. Si deseas guardar los resultados de una consulta en una tabla de destino, ejecuta la consulta con Python en lugar de usar comandos mágicos (ver el ejemplo).

Instala la biblioteca cliente para Python

A fin de instalar la biblioteca cliente de BigQuery junto con las dependencias necesarias para trabajar con DataFrames de Pandas, ingresa el siguiente comando en tu notebook:

!pip install --upgrade 'google-cloud-bigquery[bqstorage,pandas]'

Reinicia el kernel después de instalar el paquete.

Carga los comandos mágicos

Los comandos mágicos de Jupyter son accesos directos específicos para notebooks que te permiten ejecutar comandos con una sintaxis mínima. Los notebooks de Jupyter tienen muchos comandos integrados precargados. Los paquetes Python datalab y google-cloud-python implementan comandos mágicos adicionales que puedes cargar en los notebooks de Jupyter (incluido Datalab) para interactuar con Google Cloud.

datalab

Los comandos mágicos datalab se precargan en los notebooks de Datalab. Para cargar los comandos mágicos en un notebook de Jupyter, ingresa el siguiente comando:

%load_ext google.datalab.kernel

Consulta más opciones para cargar los comandos mágicos en el repositorio fuente de la biblioteca datalab.

google-cloud-bigquery

Para cargar el comando mágico de BigQuery, ingresa el siguiente comando:

%load_ext google.cloud.bigquery

Nota: %load_ext es uno de los numerosos comandos mágicos integrados de Jupyter. Consulta la documentación de Jupyter para obtener más información sobre %load_ext y otros comandos mágicos integrados.

El comando mágico de celda de BigQuery funciona en cualquier notebook en el que se instale el paquete google-cloud-bigquery.

Ejecuta consultas

En los siguientes ejemplos, se muestra cómo usar un comando mágico de celda para ejecutar una consulta. En ambos ejemplos, los resultados aparecen debajo de la celda de entrada después de la ejecución de la consulta.

datalab

Los resultados de la consulta aparecen debajo de la celda de entrada.

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

Los resultados de la consulta aparecen debajo de la celda de entrada en un DataFrame de Pandas.

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

Ejecuta una consulta y almacena los resultados en una variable

En el siguiente ejemplo, se muestra cómo ejecutar una consulta y cómo almacenar los resultados en una variable llamada my_variable.

datalab

El comando mágico de consulta datalab puede guardar una consulta de SQL sin ejecutarla si pasa un nombre con las marcas --name o -n.

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

La consulta que se guardó se puede ejecutar por separado, y los resultados se almacenan en una variable.

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

Nota: Si deseas guardar los resultados de una consulta en una tabla de destino, ejecuta la consulta con Python en lugar de usar comandos mágicos (ver el ejemplo).

Otros comandos

La biblioteca de datalab contiene comandos mágicos para muchos tipos de operaciones de BigQuery, mientras que la biblioteca de google-cloud-bigquery tiene un comando mágico de celda para ejecutar consultas. Si deseas ejecutar comandos para otras operaciones aparte de las consultas, usa la herramienta de línea de comandos de bq. En los ejemplos siguientes, se muestra cómo enumerar todas las tablas en el conjunto de datos samples del proyecto bigquery-public-data usando un comando mágico de celda datalab o un comando de shell de BigQuery.

datalab

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

Herramienta de línea de comandos de bq

Para comenzar a usar la herramienta de línea de comandos de bq, que se instala como parte de Google Cloud CLI, sigue las instrucciones de instalación de Google Cloud CLI. Ten en cuenta que los comandos de shell de un notebook deben estar precedidos por un !. Una vez que la herramienta de línea de comandos de bq esté configurada y disponible en tu notebook, ingresa el siguiente comando, que equivale al comando mágico de celda datalab que se mencionó antes.

!bq ls bigquery-public-data:samples

Nota: El primer carácter del comando es ! en lugar de % para indicar que es un comando de shell en lugar de un comando mágico. Consulta la documentación de IPython para obtener más información sobre la ejecución de comandos de shell en un notebook.

Para obtener una lista completa de comandos, ingresa lo siguiente:

!bq help

Nota: Existen herramientas de línea de comandos para muchos servicios de Google Cloud, como gcloud storage, que proporcionan una interfaz conveniente que se puede usar desde notebooks o la línea de comandos.

Usa código de Python

Además de los comandos mágicos de Jupyter, también puedes realizar operaciones de BigQuery con métodos de Python en los paquetes datalab y google-cloud-bigquery.

Ejecuta una consulta

Ambas bibliotecas permiten ejecutar consultas y mostrar los resultados como un DataFrame de Pandas.

datalab

Ver en GitHub Comentarios

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 en GitHub Comentarios

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

Carga datos en una tabla de BigQuery

En el siguiente ejemplo, se muestra cómo crear un nuevo conjunto de datos y cargar en una tabla nueva los datos de un archivo CSV ubicado en Cloud Storage.

datalab

Ver en GitHub Comentarios

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 en GitHub Comentarios

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 ver más ejemplos sobre cómo usar la biblioteca cliente de Python de BigQuery, consulta Carga datos por lotes y Transmite datos a BigQuery.

Carga un DataFrame de pandas a una tabla de BigQuery

En el siguiente ejemplo, se muestra cómo crear un conjunto de datos nuevo y cargar datos de un DataFrame de Pandas en una tabla nueva.

Algunas operaciones de BigQuery, como la creación de un conjunto de datos, requieren una ubicación. Si se suministra una ubicación al cliente de google-cloud-bigquery durante la inicialización, esa será la ubicación predeterminada de los trabajos, los conjuntos de datos y las tablas que se creen con el cliente. La biblioteca de datalab no proporciona una manera de especificar las ubicaciones de los trabajos o los conjuntos de datos, lo cual puede llevar a que observes comportamientos inesperados. Consulta Ubicaciones de conjuntos de datos para obtener más información.

datalab

La biblioteca de datalab realiza una inserción de transmisión cuando se cargan datos de un DataFrame de Pandas en una tabla de BigQuery. Debido a esto, es posible que los datos no estén disponibles de forma inmediata para realizar consultas. Consulta Transmite datos a BigQuery para obtener más información.

Ver en GitHub Comentarios

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

La biblioteca cliente de BigQuery convierte el DataFrame de Pandas al formato Parquet y realiza un trabajo de carga (y no una inserción de transmisión). Los datos están disponibles de inmediato una vez que finaliza el trabajo de carga.

Ver en GitHub Comentarios

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.