Vom Python-Paket "datalab" migrieren

Das Python-Paket datalab wird für die Interaktion mit Google Cloud-Diensten über Datalab-Notebooks verwendet. Das Python-Paket datalab enthält Jupyter-Magien und Python-Module wie google.datalab.bigquery, die einen Teil der BigQuery API-Methoden unterstützen.

Die BigQuery-Clientbibliothek google-cloud-bigquery ist die offizielle Python-Bibliothek für die Interaktion mit BigQuery. Die Clientbibliothek bietet eine Jupyter-Zellmagie zum Ausführen von Abfragen. Diese Funktionen ermöglichen das Senden und Abrufen von Daten mithilfe von pandas-DataFrames und die Bibliothek unterstützt den gesamten Funktionsumfang von BigQuery. Die folgenden Codebeispiele veranschaulichen, wie Entwickler, die mit dem Python-Paket datalab bereits vertraut sind, allgemeine BigQuery-Vorgänge mit der Bibliothek google-cloud-bigquery ausführen können.

In der Datei requirements.txt finden Sie die Versionen der Bibliotheken, die für diese Code-Snippets verwendet wurden.

Hinweis: Der Begriff datalab bezieht sich in dieser Anleitung auf das Python-Paket datalab und nicht auf den gehosteten Notebook-Dienst Datalab.

Jupyter-Magien und Shell-Befehle verwenden

Beide Bibliotheken unterstützen das Abfragen von in BigQuery gespeicherten Daten mithilfe einer Zellmagie. Die wichtigsten Unterschiede zwischen den beiden Bibliotheken in Bezug auf Magien sind folgende:

	datalab	google-cloud-bigquery
Name der Magie	bq	bigquery
Name der Jupyter-Erweiterung (wird zum Laden der Magien verwendet)	google.datalab.kernel	google.cloud.bigquery
Ausführung von Abfragen	Die Definition und Ausführung von Abfragen kann in separaten Schritten erfolgen.	Die Abfrage wird immer sofort ausgeführt, wenn der magische Befehl ausgeführt wird.
Von Magien unterstützte Funktionen	Einige Funktionen werden nicht unterstützt.	Mit Magien können nur Abfragen ausgeführt werden. Verwenden Sie für andere BigQuery-Funktionen das Befehlszeilentool oder die Methode google.cloud.bigquery.Client.
Abfrageergebnisse speichern	Abfrageergebnisse können über die Abfragemagie in einer Zieltabelle gespeichert werden, jedoch nicht in einer Variablen. Zum Speichern der Abfrageergebnisse für eine Variable führen Sie die Abfrage mit Python anstelle von Magien aus (siehe Beispiel).	Abfrageergebnisse können über die Abfragemagie in einer Variablen gespeichert werden, jedoch nicht in einer Zieltabelle. Zum Speichern der Abfrageergebnisse in einer Zieltabelle führen Sie die Abfrage mit Python anstelle von Magien aus (siehe Beispiel).

Python-Clientbibliothek installieren

Geben Sie den folgenden Befehl in Ihrem Notebook ein, um die BigQuery-Clientbibliothek zusammen mit den Abhängigkeiten zu installieren, die für die Arbeit mit pandas-DataFrames erforderlich sind:

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

Hinweis: Möglicherweise müssen Sie nach der Installation des Pakets den Kernel neu starten.

Magien laden

Jupyter-Magien sind Notebook-spezifische Verknüpfungen, mit denen Sie Befehle mit minimaler Syntax ausführen können. In Jupyter-Notebooks sind viele integrierte Befehle vorinstalliert. Die Python-Pakete datalab und google-cloud-python enthalten zusätzliche magische Befehle, die Sie in Jupyter-Notebooks (einschließlich Datalab) laden können, um mit der Google Cloud zu interagieren.

datalab

datalab-Magien sind in Datalab-Notebooks vorinstalliert. Geben Sie den folgenden Befehl ein, um die Magien in ein Jupyter-Notebook zu laden:

%load_ext google.datalab.kernel

Weitere Optionen zum Laden von Magien finden Sie im datalab der Bibliothek Quell-Repository.

google-cloud-bigquery

Geben Sie den folgenden Befehl ein, um die BigQuery-Magie zu laden:

%load_ext google.cloud.bigquery

Hinweis: %load_ext ist einer der vielen in Jupyter integrierten magischen Befehle. Weitere Informationen zu %load_ext und weiteren integrierten magischen Befehlen finden Sie in der Jupyter-Dokumentation.

Die BigQuery-Zellmagie funktioniert in jedem Notebook, in dem das Paket google-cloud-bigquery installiert ist. Sie benötigen eine Clientbibliothek ab Version 0.32.0, um Zellmagien verwenden zu können.

Abfragen ausführen

Die folgenden Beispiele zeigen, wie Sie mit einer Zellmagie eine Abfrage ausführen. In beiden Beispielen wird die Abfrage ausgeführt und die Ergebnisse werden unter der Eingabezelle angezeigt.

datalab

Die Abfrageergebnisse werden unterhalb der Eingabezelle als QueryResultsTable angezeigt.

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

Die Abfrageergebnisse werden unterhalb der Eingabezelle in einem pandas-DataFrame angezeigt.

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

Abfrage ausführen und Ergebnisse in einer Variablen speichern

Das folgende Beispiel zeigt, wie Sie eine Abfrage ausführen und die Ergebnisse in einer Variablen mit dem Namen my_variable speichern können.

datalab

Mit der Abfragemagie datalab kann eine SQL-Abfrage gespeichert werden, ohne sie auszuführen. Dazu wird ein Name mit dem Flag --name oder -n übergeben.

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

Die gespeicherte Abfrage kann dann separat ausgeführt werden. Ihre Ergebnisse werden in einer Variablen gespeichert.

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

Hinweis: Zum Speichern der Abfrageergebnisse in einer Zieltabelle führen Sie die Abfrage mit Python anstelle von Magien aus (siehe Beispiel).

Parametrisierte Abfrage ausführen

Im folgenden Beispiel wird gezeigt, wie eine parametrisierte Abfrage ausgeführt wird. Bei einer parametrisierten Abfrage können Sie Abfrageparameter definieren und die Abfrage in separaten Zellen ausführen. Weitere Informationen finden Sie unter Parametrisierte Abfragen ausführen.

datalab

Definieren Sie die Abfrage.

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

Legen Sie die Parameter fest.

corpus_name = "hamlet"
limit = 10

Führen Sie die Abfrage aus.

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

Definieren Sie die Parameter.

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

Definieren Sie die Abfrage und führen Sie sie aus

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

Weitere Befehle

Die Bibliothek datalab bietet für viele Arten von BigQuery-Vorgängen Magien, während die Bibliothek google-cloud-bigquery nur eine einzige Zellmagie zum Ausführen von Abfragen enthält. Verwenden Sie das BigQuery-Befehlszeilentool, um andere Befehle als Abfragen auszuführen. In folgenden Beispielen wird veranschaulicht, wie mit einer datalab-Zellmagie oder einem BigQuery-Shell-Befehl alle Tabellen im Dataset samples des Projekts bigquery-public-data aufgelistet werden können.

datalab

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

BigQuery-Befehlszeilentool

Das BigQuery-Befehlszeilentool wird als Teil des Cloud SDK installiert. Informationen für den Einstieg finden Sie in der Installationsanleitung für das Cloud SDK. Beachten Sie, dass den Shell-Befehlen in einem Notebook das Zeichen ! vorangestellt werden muss. Wenn das BigQuery-Befehlszeilentool eingerichtet und in Ihrem Notebook verfügbar ist, geben Sie den folgenden Befehl ein. Dieser Befehl entspricht der oben beschriebenen datalab-Zellmagie.

!bq ls bigquery-public-data:samples

Hinweis: Das erste Zeichen des Befehls ist ! anstelle von %. Damit wird angezeigt, dass es sich um einen Shell-Befehl und nicht um eine Magie handelt. Weitere Informationen zum Ausführen von Shell-Befehlen in einem Notebook finden Sie in der IPython-Dokumentation.

Geben Sie Folgendes ein, um eine vollständige Liste der Befehle aufzurufen:

!bq help

Hinweis: Für viele Google Cloud-Dienste gibt es Befehlszeilentools, wie z. B. gsutil. Diese bieten eine Magien ähnelnde Oberfläche und können aus Notebooks oder über die Befehlszeile verwendet werden.

Python-Code verwenden

Neben Jupyter-Magien können Sie BigQuery-Vorgänge auch mit Python-Methoden in den Paketen datalab und google-cloud-bigquery ausführen.

Abfrage ausführen

Beide Bibliotheken unterstützen die Ausführung von Abfragen und die Rückgabe der Ergebnisse als pandas-DataFrame.

datalab

Auf GitHub ansehen 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

Auf GitHub ansehen 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()

Daten in eine BigQuery-Tabelle laden

Das folgende Beispiel zeigt, wie Sie ein neues Dataset erstellen und Daten aus einer in Cloud Storage gespeicherten CSV-Datei in eine neue Tabelle laden.

datalab

Auf GitHub ansehen 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

Auf GitHub ansehen 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.

Weitere Beispiele für die Verwendung der Python-Clientbibliothek für BigQuery finden Sie unter Daten aus Cloud Storage laden, Daten aus einer lokalen Datenquelle in BigQuery laden und Daten in BigQuery streamen.

pandas-DataFrame in eine BigQuery-Tabelle laden

Im folgenden Beispiel wird gezeigt, wie Sie ein neues Dataset erstellen und Daten aus einem pandas-DataFrame in eine neue Tabelle laden.

Für bestimmte BigQuery-Vorgänge, z. B. zum Erstellen eines Datasets, werden Standorte benötigt. Wenn bei der Initialisierung eines google-cloud-bigquery-Clients ein Standort festgelegt wird, ist dies der Standardstandort für Jobs, Datasets und Tabellen, die mit dem Client erstellt werden. Die Bibliothek datalab bietet keine Möglichkeit, Standorte für Datasets oder Jobs festzulegen, was zu unerwartetem Verhalten führen kann. Weitere Informationen finden Sie unter Dataset-Standorte.

datalab

Die Bibliothek datalab führt eine Streaming-Insert-Anweisung aus, wenn Daten aus einem pandas-DataFrame in eine BigQuery-Tabelle geladen werden. Aus diesem Grund stehen die Daten möglicherweise nicht sofort für Abfragen zur Verfügung. Weitere Informationen finden Sie unter Daten in BigQuery streamen.

Auf GitHub ansehen 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

Die BigQuery-Clientbibliothek konvertiert den pandas-DataFrame in das Parquet-Format und führt einen Ladejob aus (im Gegensatz zu einer Streaming-Insert-Anweisung). Die Daten stehen nach Abschluss des Ladejobs sofort zur Verfügung.

Auf GitHub ansehen 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.