Python-Bibliothek auswählen

Je nach Anwendungsfall können Sie aus drei Python-Bibliotheken in BigQuery auswählen.

	Anwendungsfall	Verwaltet von	Beschreibung
BigQuery DataFrames	Python-basierte Datenverarbeitung und ML-Vorgänge mit serverseitiger Verarbeitung (z. B. Verwendung von Slots)	Google	Pandas und Scikit-Learn APIs, die mit serverseitigem Push-down implementiert wurden. Weitere Informationen finden Sie unter Einführung in BigQuery DataFrames.
pandas-gbq	Python-basierte Datenverarbeitung mit clientseitiger Datenkopie	Open-Source-Bibliothek, die von PyData und freiwilligen Contributors verwaltet wird	Ermöglicht das Verschieben von Daten zu und von Python DataFrames auf der Clientseite. Weitere Informationen finden Sie in der Dokumentation und im Quellcode.
google-cloud-bigquery	Bereitstellung, Verwaltung und SQL-basierte Abfragen in BigQuery	Open-Source-Bibliothek, die von Google verwaltet wird	Python-Paket, das alle BigQuery APIs umschließt Weitere Informationen finden Sie in der Dokumentation und im Quellcode.

pandas-gbq und google-cloud-bigquery verwenden

Die pandas-gbq-Bibliothek bietet eine einfache Schnittstelle zum Ausführen von Abfragen und zum Hochladen von pandas-Dataframes in BigQuery. Es ist ein dünner Wrapper für die BigQuery-Clientbibliothek google-cloud-bigquery. Beide Bibliotheken unterstützen Sie bei der Datenanalyse mit SQL.

Bibliotheken installieren

Um die Codebeispiele in diesem Leitfaden zu verwenden, installieren Sie das Paket pandas-gbq und die BigQuery-Python-Clientbibliotheken.

PIP

Installieren Sie die Pakete pandas-gbq und google-cloud-bigquery.

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

Conda

Installieren Sie die Conda-Pakete pandas-gbq und google-cloud-bigquery aus dem Community-Kanal conda-forge.

conda install -c conda-forge pandas-gbq google-cloud-bigquery

Abfragen ausführen

Beide Bibliotheken unterstützen das Abfragen von in BigQuery gespeicherten Daten. Die wichtigsten Unterschiede zwischen den Bibliotheken sind:

	pandas-gbq	google-cloud-bigquery
Standardmäßige SQL-Syntax	GoogleSQL (konfigurierbar mit `pandas_gbq.context.dialect`)	GoogleSQL
Abfragekonfiguration	Wird als Wörterbuch in dem in der BigQuery-REST-Referenz angegebenen Format gesendet	Verwendet die Klasse `QueryJobConfig`. Sie enthält Attribute für die verschiedenen API-Konfigurationsoptionen.

Daten mit der GoogleSQL-Syntax abfragen

Im folgenden Beispiel wird gezeigt, wie eine GoogleSQL-Abfrage mit und ohne explizite Angabe eines Projekts ausgeführt wird. Falls kein Projekt angegeben ist, wird das Projekt in beiden Bibliotheken anhand der Standardanmeldedaten ermittelt.

pandas-gbq:

import pandas

sql = """
    SELECT name
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
"""

# Run a Standard SQL query using the environment's default project
df = pandas.read_gbq(sql, dialect="standard")

# Run a Standard SQL query with the project set explicitly
project_id = "your-project-id"
df = pandas.read_gbq(sql, project_id=project_id, dialect="standard")

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

# Run a Standard SQL query using the environment's default project
df = client.query(sql).to_dataframe()

# Run a Standard SQL query with the project set explicitly
project_id = "your-project-id"
df = client.query(sql, project=project_id).to_dataframe()

Daten mit der Legacy-SQL-Syntax abfragen

Im folgenden Beispiel wird gezeigt, wie eine Abfrage mit der Legacy-SQL-Syntax ausgeführt wird. Eine Anleitung zum Aktualisieren Ihrer Abfragen auf GoogleSQL finden Sie im GoogleSQL-Migrationsleitfaden.

pandas-gbq:

import pandas

sql = """
    SELECT name
    FROM [bigquery-public-data:usa_names.usa_1910_current]
    WHERE state = 'TX'
    LIMIT 100
"""

df = pandas.read_gbq(sql, dialect="legacy")

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
"""
query_config = bigquery.QueryJobConfig(use_legacy_sql=True)

df = client.query(sql, job_config=query_config).to_dataframe()

Mit der BigQuery Storage API umfangreiche Ergebnisse herunterladen

Verwenden Sie die BigQuery Storage API, um umfangreiche Ergebnisse 15- bis 31-mal schneller herunterzuladen.

pandas-gbq:

import pandas

sql = "SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`"

# Use the BigQuery Storage API to download results more quickly.
df = pandas.read_gbq(sql, dialect="standard", use_bqstorage_api=True)

google-cloud-bigquery:

from google.cloud import bigquery

client = bigquery.Client()
sql = "SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`"

# The client library uses the BigQuery Storage API to download results to a
# pandas dataframe if the API is enabled on the project, the
# `google-cloud-bigquery-storage` package is installed, and the `pyarrow`
# package is installed.
df = client.query(sql).to_dataframe()

Abfrage mit einer Konfiguration ausführen

Das Senden einer Konfiguration mit einer BigQuery API-Anfrage ist für bestimmte komplexe Vorgänge erforderlich, beispielsweise für das Ausführen einer parametrisierten Abfrage oder das Angeben einer Zieltabelle zum Speichern der Abfrageergebnisse. In pandas-gbq muss die Konfiguration als Wörterbuch in dem in der BigQuery-REST-Referenz angegebenen Format gesendet werden. In google-cloud-bigquery werden Jobkonfigurationsklassen bereitgestellt, beispielsweise QueryJobConfig, die die erforderlichen Attribute zur Konfiguration komplexer Jobs enthalten.

Im folgenden Beispiel wird gezeigt, wie eine Abfrage mit benannten Parametern ausgeführt wird.

pandas-gbq:

import pandas

sql = """
    SELECT name
    FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = @state
    LIMIT @limit
"""
query_config = {
    "query": {
        "parameterMode": "NAMED",
        "queryParameters": [
            {
                "name": "state",
                "parameterType": {"type": "STRING"},
                "parameterValue": {"value": "TX"},
            },
            {
                "name": "limit",
                "parameterType": {"type": "INTEGER"},
                "parameterValue": {"value": 100},
            },
        ],
    }
}

df = pandas.read_gbq(sql, configuration=query_config)

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 = @state
    LIMIT @limit
"""
query_config = bigquery.QueryJobConfig(
    query_parameters=[
        bigquery.ScalarQueryParameter("state", "STRING", "TX"),
        bigquery.ScalarQueryParameter("limit", "INTEGER", 100),
    ]
)

df = client.query(sql, job_config=query_config).to_dataframe()

Einen pandas DataFrame in eine BigQuery-Tabelle laden

Beide Bibliotheken unterstützen das Hochladen von Daten aus einem pandas DataFrame in eine neue BigQuery-Tabelle. Die Hauptunterschiede sind:

	pandas-gbq	google-cloud-bigquery
Unterstützte Typen	Konvertiert den DataFrame in das CSV-Format, bevor er an die API gesendet wird. Dabei werden keine verschachtelten oder Array-Werte unterstützt.	Konvertiert den DataFrame in das Parquet- oder CSV-Format, bevor er an die API gesendet wird. Dabei werden verschachtelte und Array-Werte unterstützt. Wählen Sie Parquet für Struktur- und Arraywerte und CSV für Flexibilität bei der Serialisierung von Datum und Uhrzeit aus. Parquet ist die Standardeinstellung. Die Installation von `pyarrow`, der Parquet-Engine zum Senden der DataFrame-Daten an die BigQuery API, ist erforderlich, wenn Sie den DataFrame in eine Tabelle laden möchten.
Ladekonfiguration	Wird als Wörterbuch in dem in der BigQuery-REST-Referenz angegebenen Format gesendet	Verwendet die Klasse `LoadJobConfig`. Sie enthält Attribute für die verschiedenen API-Konfigurationsoptionen.

pandas-gbq:

import pandas

df = pandas.DataFrame(
    {
        "my_string": ["a", "b", "c"],
        "my_int64": [1, 2, 3],
        "my_float64": [4.0, 5.0, 6.0],
        "my_timestamp": [
            pandas.Timestamp("1998-09-04T16:03:14"),
            pandas.Timestamp("2010-09-13T12:03:45"),
            pandas.Timestamp("2015-10-02T16:00:00"),
        ],
    }
)
table_id = "my_dataset.new_table"

df.to_gbq(table_id)

google-cloud-bigquery:

Das Paket google-cloud-bigquery weist die pyarrow-Bibliothek an, einen pandas-DataFrame in eine Parquet-Datei zu serialisieren.

Installieren Sie das Paket pyarrow:

 conda install -c conda-forge pyarrow

oder

 pip install pyarrow

from google.cloud import bigquery
import pandas

df = pandas.DataFrame(
    {
        "my_string": ["a", "b", "c"],
        "my_int64": [1, 2, 3],
        "my_float64": [4.0, 5.0, 6.0],
        "my_timestamp": [
            pandas.Timestamp("1998-09-04T16:03:14"),
            pandas.Timestamp("2010-09-13T12:03:45"),
            pandas.Timestamp("2015-10-02T16:00:00"),
        ],
    }
)
client = bigquery.Client()
table_id = "my_dataset.new_table"
# Since string columns use the "object" dtype, pass in a (partial) schema
# to ensure the correct BigQuery data type.
job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("my_string", "STRING"),
    ]
)

job = client.load_table_from_dataframe(df, table_id, job_config=job_config)

# Wait for the load job to complete.
job.result()

Von pandas-gbq nicht unterstützte Funktionen

Die pandas-gbq-Bibliothek bietet zwar eine nützliche Schnittstelle zum Abfragen und Schreiben von Daten in Tabellen, sie deckt jedoch viele Features der BigQuery API nicht ab. Dazu gehören unter anderem:

Datasets verwalten, einschließlich Datasets erstellen, Dataset-Attribute aktualisieren und Datasets löschen
Laden von Daten in BigQuery aus anderen Formaten als pandas DataFrames
Tabellen verwalten, einschließlich Tabellen in einem Dataset auflisten, Tabellendaten kopieren und Tabellen löschen
BigQuery-Daten direkt nach Google Cloud Storage exportieren

Fehler bei Verbindungspools beheben

Fehlerstring: Connection pool is full, discarding connection: bigquery.googleapis.com. Connection pool size: 10

Wenn Sie das Standard-BigQuery-Clientobjekt in Python verwenden, sind Sie auf maximal zehn Threads beschränkt, da die Standardpoolgröße für den Python HTTPAdapter 10 ist. Wenn Sie mehr als zehn Verbindungen verwenden möchten, erstellen Sie ein benutzerdefiniertes requests.adapters.HTTPAdapter-Objekt. Beispiele:

client = bigquery.Client()
adapter = requests.adapters.HTTPAdapter(pool_connections=128,
pool_maxsize=128,max_retries=3)
client._http.mount("https://",adapter)
client._http._auth_request.session.mount("https://",adapter)
query_job = client.query(QUERY)