从 datalab Python 软件包迁移

datalab Python 软件包用于通过 Datalab 笔记本与 Google Cloud 服务进行交互。datalab Python 软件包中包含支持部分 BigQuery API 方法的 Jupyter 魔法命令和 Python 模块,例如 google.datalab.bigquery

BigQuery 客户端库 google-cloud-bigquery 是用于与 BigQuery 进行交互的 Python 官方库。该客户端库提供了一个用于运行查询的 Jupyter 单元魔法命令,其功能是使用 Pandas DataFrame 发送和检索数据。此库支持全部 BigQuery 功能。下面的代码示例演示了熟悉 datalab Python 软件包的开发者如何使用 google-cloud-bigquery 库来执行常见的 BigQuery 操作。

如需查看用于这些代码段的库版本,请参阅 requirements.txt 文件

使用 Jupyter 魔法命令和 shell 命令

这两个库都支持使用单元魔法命令查询 BigQuery 中存储的数据。但它们在使用魔法命令上存在以下主要差异:

datalab google-cloud-bigquery
魔法命令名称 bq bigquery
Jupyter 扩展程序名称(用于加载魔法命令) google.datalab.kernel google.cloud.bigquery
查询执行 查询定义和执行可以在不同的步骤中进行。 运行魔法命令时,始终会立即执行查询。
魔法命令所涵盖的功能 不支持某些功能。 只有查询可以通过魔法命令执行。对于其他 BigQuery 功能,请使用命令行工具google.cloud.bigquery.Client 方法。
保存查询结果 查询结果可通过查询魔法命令保存到目标表中,但不能保存到变量中。如需将查询结果保存到变量中,请使用 python 而非魔法命令来执行查询(请参阅示例)。 查询结果可通过查询魔法命令保存到变量中,但不能保存到目标表中。如需将查询结果保存到目标表中,请使用 python 而非魔法命令来运行查询(请参阅示例)。

安装 Python 客户端库

如需安装 BigQuery 客户端库以及使用 Pandas DataFrame 所需的依赖项,请在笔记本中输入以下命令:

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

加载魔法命令

Jupyter 魔法命令是笔记本专用的快捷命令,可让您以最简洁的语法来运行命令。Jupyter 笔记本已预先加载许多内置命令datalabgoogle-cloud-python Python 软件包还实现了其他一些魔法命令,您可以将这些命令加载到 Jupyter 笔记本(包括 Datalab)中以与 Google Cloud 进行交互。

datalab

datalab 魔法命令已预先加载到 Datalab 笔记本中。如需在 Jupyter 笔记本中加载此魔法命令,请输入以下命令:

%load_ext google.datalab.kernel

如需查看更多魔法命令加载选项,请参阅 datalab源代码库

google-cloud-bigquery

如需加载 BigQuery 魔法命令,请输入以下命令:

%load_ext google.cloud.bigquery

BigQuery 单元魔法命令适用于所有安装了 google-cloud-bigquery 软件包的笔记本。如需使用单元魔法命令,您必须使用客户端库 0.32.0 或更高版本。

运行查询

以下示例演示了如何使用单元魔法命令来运行查询。这两个示例都运行查询并在输入单元下方显示结果。

datalab

查询结果会以 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

查询结果会以 Pandas DataFrame 的形式显示在输入单元下方。
%%bigquery
SELECT word, SUM(word_count) as count
FROM `bigquery-public-data.samples.shakespeare`
GROUP BY word
ORDER BY count ASC
LIMIT 100

运行查询并将结果存储在变量中

以下示例演示了如何运行查询,以及如何将结果存储在名为 my_variable 的变量中。

datalab

datalab 查询魔法命令可通过使用 --name-n 标志传递名称来保存 SQL 查询,而无需运行该查询。
%%bq query -n my_query
SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
WHERE state = "TX"
LIMIT 100
然后,可以单独执行保存的查询,并将结果存储到变量中。
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

运行参数化查询

以下示例演示了如何运行参数化查询。运行参数化查询可让您定义查询参数并在单独的单元中运行查询。如需了解详情,请参阅运行参数化查询

datalab

定义查询。
%%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
设置参数。
corpus_name = "hamlet"
limit = 10
执行查询。
%%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

定义参数。
params = {"corpus_name": "hamlet", "limit": 10}
定义并执行查询。
%%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

其他命令

datalab 库包含适用于许多 BigQuery 操作类型的魔法命令,而 google-cloud-bigquery 库只有一个用于运行查询的单元魔法命令。如需运行查询之外的其他操作命令,请使用 bq 命令行工具。以下示例演示了如何使用 datalab 单元魔法命令或 BigQuery shell 命令列出 bigquery-public-data 项目的 samples 数据集内的所有表。

datalab

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

bq 命令行工具

如需开始使用作为 Cloud SDK 的一部分安装的 bq 命令行工具,请按照 Cloud SDK 安装说明进行操作。请注意,您必须在笔记本中的 shell 命令前面加上 !。在笔记本中设置好 bq 命令行工具且可以使用后,输入以下命令,该命令等效于上面的 datalab 单元魔法命令。

!bq ls bigquery-public-data:samples

如需完整命令列表,请输入以下命令:

!bq help

使用 Python 代码

除了 Jupyter 魔法命令之外,您还可以在 datalabgoogle-cloud-bigquery 软件包中使用 Python 方法执行 BigQuery 操作。

运行查询

这两个库都支持运行查询并以 Pandas DataFrame 形式返回结果。

datalab

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

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

将数据加载到 BigQuery 表中

以下示例演示了如何创建新数据集,并将 Cloud Storage 中 CSV 文件的数据加载到新表中。

datalab

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

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.

如需查看使用 BigQuery Python 客户端库的更多示例,请参阅从 Cloud Storage 加载数据将本地数据源中的数据加载到 BigQuery 以及将数据流式插入到 BigQuery

将 Pandas DataFrame 数据加载到 BigQuery 表中

以下示例演示了如何创建新数据集,并将 Pandas DataFrame 数据加载到新表中。

某些 BigQuery 操作(例如创建数据集)需要提供位置。如果在初始化 google-cloud-bigquery 客户端时向其提供了位置,则此位置将成为使用该客户端创建的作业、数据集和表的默认位置。datalab 库未提供数据集或作业位置的指定方法,这可能会导致意外行为。如需了解详情,请参阅数据集位置

datalab

将 Pandas DataFrame 数据加载到 BigQuery 表时,datalab 库会执行流式插入。因此,查询可能无法立即找到数据。如需了解详情,请参阅将数据流式插入到 BigQuery
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

BigQuery 客户端库会将 Pandas DataFrame 数据转换为 Parquet 格式并执行加载作业(而不是流式插入)。 完成加载作业后,数据将立即可用。
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.