datalab Python パッケージからの移行

datalab Python パッケージは、Datalab ノートブックで Google Cloud サービスとやり取りするために使用されます。datalab Python パッケージには、BigQuery API メソッドのサブセットをサポートする、google.datalab.bigquery などの Jupyter マジックと Python モジュールが含まれています。

BigQuery クライアント ライブラリ（google-cloud-bigquery）は、BigQuery の操作に使用される公式の Python ライブラリです。このクライアント ライブラリでは、クエリ実行用の Jupyter セルマジック、pandas DataFrame を使用してデータを送受信するための関数を備え、BigQuery のフル機能もサポートしています。以下のコード例では、datalab Python パッケージに精通しているデベロッパー向けに、google-cloud-bigquery ライブラリを使用して BigQuery の一般的なオペレーションを実行する方法を説明します。

以下のコード スニペットで使用されているライブラリのバージョンを確認するには、requirements.txt ファイルをご覧ください。

注: このガイドでは、datalab はホスト型ノートブック サービスである Datalab ではなく、datalab Python パッケージを指します。

Jupyter マジックとシェルコマンドを使う

どちらのライブラリでも、BigQuery に保存されているデータにセルマジックでクエリを行うことができます。2 つのライブラリのマジックに対するアプローチの主な違いは以下のとおりです。

	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[bqstorage,pandas]'

パッケージをインストールした後、カーネルを再起動します。

マジックの読み込み

Jupyter マジックはノートブック固有のショートカットです。これを使用すると最小限の構文でコマンドを実行できます。Jupyter ノートブックには、あらかじめ多数の組み込みコマンドが読み込まれています。datalab および google-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

注: %load_ext は、Jupyter に組み込まれている数多くのマジック コマンドの 1 つです。%load_ext やその他のマジック コマンドの詳細については、Jupyter のドキュメントをご覧ください。

BigQuery のセルマジックは、google-cloud-bigquery パッケージがインストールされているノートブックであれば動作します。

クエリの実行

次の例は、セルマジックを使用したクエリの実行方法を示しています。どちらの例も、クエリを実行し、結果を入力セルの下に表示します。

datalab

クエリ結果が入力セルの下に表示されます。

%%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 クエリマジックを使用すると、SQL クエリを実行することなく、その内容を --name または -n フラグで指定した名前の変数に保存できます。

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

注: 抽出先テーブルに保存するには、マジックの代わりに python を使用してクエリを実行します（例を参照）。

その他のコマンド

google-cloud-bigquery ライブラリには、クエリを実行するためのセルマジックが 1 つあるだけですが、datalab ライブラリには、さまざまな種類の BigQuery オペレーションのためのマジックがあります。クエリ以外のオペレーションをコマンドで実行するには、コマンドライン ツールを使用します。次の例では、datalab セルマジックまたは BigQuery シェルコマンドを使用して、bigquery-public-data プロジェクトの samples データセット内のすべてのテーブルを表示します。

datalab

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

bq コマンドライン ツール

Google Cloud CLI の一部としてインストールされる bq コマンドライン ツールを使用するには、Google Cloud CLI のインストール手順に沿ってください。ノートブックではシェルコマンドの前には ! を付けなければなりません。bp コマンドライン ツールが設定され、ノートブックから利用可能になったら、次のコマンドを入力します。これは、上記の datalab セルマジックと同等のコマンドです。

!bq ls bigquery-public-data:samples

注: このコマンドの最初の文字が % ではなく ! であるので、マジックではなくシェルコマンドであることを示しています。ノートブックでシェルコマンドを実行する方法の詳細については、IPython のドキュメントをご覧ください。

すべてのコマンドの一覧を表示するには、次のように入力します。

!bq help

注: Google Cloud サービス用のコマンドライン ツールには、gcloud storage のように、ノートブックやコマンドラインから使用できる便利なインターフェースを持つものが多数あります。

Python コードの使用

Jupyter マジックに加えて、datalab および google-cloud-bigquery パッケージの両方で Python メソッドを使用して BigQuery オペレーションを実行することもできます。

クエリの実行

どちらのライブラリでも、クエリを実行して、結果を pandas DataFrame として返すことができます。

datalab

GitHub で表示 フィードバック

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

GitHub で表示 フィードバック

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

GitHub で表示 フィードバック

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

GitHub で表示 フィードバック

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 クライアント ライブラリの使用例については、データのバッチ読み込みと BigQuery へのデータのストリーミングをご覧ください。

BigQuery テーブルに pandas DataFrame を読み込む

次の例は、新しいデータセットを作成し、pandas DataFrame から新しいテーブルにデータを読み込む方法を示しています。

データセットの作成など、特定の BigQuery オペレーションにはロケーションが必要です。google-cloud-bigquery クライアントが初期化されるときにロケーションを指定すると、そのロケーションが、クライアントで作成されたジョブ、データセット、テーブルのデフォルト ロケーションになります。datalab ライブラリには、データセットやジョブのロケーションを指定する方法がないため、予期しない動作となる可能性があります。詳細については、データセットのロケーションをご覧ください。

datalab

datalab ライブラリは、pandas DataFrame から BigQuery テーブルにデータを読み込むときに、ストリーミング挿入を行います。このため、クエリでデータをすぐに利用できない場合があります。詳細については、BigQuery へのデータのストリーミングをご覧ください。

GitHub で表示 フィードバック

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 形式に変換して、読み込みジョブを実行します。読み込みジョブが完了すると、すぐにデータが利用可能となります。

GitHub で表示 フィードバック

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.