Open-Source-Python-Bibliotheken verwenden

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

Anwendungsfall Maximale Datengröße Beschreibung
bigquery-dataframes Python-basierte Datenverarbeitung und ML-Vorgänge mit serverseitiger Verarbeitung Skalierbar auf Datasets mit mehreren Terabyte (serverseitiges Pushdown) Pandas- und scikit-learn-APIs, die mit serverseitigem Pushdown implementiert wurden. Weitere Informationen finden Sie unter Einführung in BigQuery DataFrames.
pandas-gbq Python-basierte Datenverarbeitung mit clientseitiger Datenkopie Durch den Clientspeicher begrenzt 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 BigQuery-Bereitstellung, ‑Verwaltung und SQL-basierte Abfragen Durch den Clientspeicher begrenzt Python-Paket, das alle BigQuery-APIs umschließt. Weitere Informationen finden Sie in der Dokumentation und im Quellcode.

BigQuery DataFrames, pandas-gbq und google-cloud-bigquery verwenden

Die Bibliothek `bigquery-dataframes` (bigframes) bietet eine Pythonic DataFrame und eine ML API mit serverseitiger Abfrageverarbeitung. Die Bibliothek pandas-gbq 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.

Bibliotheken installieren

Um die Codebeispiele in diesem Leitfaden zu verwenden, installieren Sie die Pakete bigframes, pandas-gbq und google-cloud-bigquery:

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

Abfragen ausführen

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

bigquery-dataframes pandas-gbq google-cloud-bigquery
Standardmäßige SQL-Syntax GoogleSQL GoogleSQL (konfigurierbar mit pandas_gbq.context.dialect) GoogleSQL
Abfragekonfiguration Konfigurierbar mit bpd.options.bigquery oder read_gbq-Parametern Als Wörterbuch im Format einer Abfrageanfrage 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 allen drei Bibliotheken anhand der Standardanmeldedaten ermittelt.

bigquery-dataframes 

import bigframes.pandas as bpd

# Set partial ordering mode as the default configuration for BigQuery
# DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_standard_sql(project_id: str = "your-project-id") -> bpd.DataFrame:
    sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
    """

    # Run a query alongside existing SQL. The project will be determined from
    # default credentials.
    df = bpd.read_gbq(sql)

    # Run a query after explicitly specifying a project.
    bpd.close_session()
    bpd.options.bigquery.project = project_id
    df = bpd.read_gbq(sql)
    return df

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.

bigquery-dataframes

BigQuery DataFrames unterstützt die Legacy-SQL-Syntax nicht. Verwenden Sie stattdessen die GoogleSQL-Syntax.

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.

bigquery-dataframes 

import bigframes.pandas as bpd

import pandas as pd

# Set partial ordering mode as the default configuration for BigQuery
# DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_bqstorage() -> pd.DataFrame:
    sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = 'TX'
    LIMIT 100
    """

    # Read query results into a server-side DataFrame without downloading data.
    df = bpd.read_gbq(sql)

    # When downloading results to an in-memory pandas DataFrame,
    # bigquery-dataframes automatically uses the BigQuery Storage API if
    # installed.
    pandas_df = df.to_pandas()
    return pandas_df

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 bigquery-dataframes (read_gbq) und pandas-gbq muss die Konfiguration als Wörterbuch im Format einer Abfrageanfrage 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.

bigquery-dataframes 

import bigframes.pandas as bpd

# Set partial ordering mode as the default configuration for BigQuery
# DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_parameters() -> bpd.DataFrame:
    sql = """
    SELECT name FROM `bigquery-public-data.usa_names.usa_1910_current`
    WHERE state = @state
    LIMIT 100
    """

    query_config = {
        "query": {
            "parameterMode": "NAMED",
            "queryParameters": [
                {
                    "name": "state",
                    "parameterType": {"type": "STRING"},
                    "parameterValue": {"value": "TX"},
                }
            ],
        }
    }

    df = bpd.read_gbq(sql, configuration=query_config)
    return df

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

pandas-DataFrame in eine BigQuery-Tabelle laden

Sowohl pandas-gbq als auch google-cloud-bigquery 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 Array-Werte und CSV für die Flexibilität bei der Datums- und Zeitserialisierung aus. Parquet ist die Standardauswahl. 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 Sie können optional ein Tabellenschema angeben. 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:

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 und bigquery-dataframes nicht unterstützte Funktionen

Die Bibliotheken pandas-gbq und bigquery-dataframes bieten zwar nützliche Schnittstellen zum Abfragen und Schreiben von Daten in Tabellen, sie decken jedoch viele Features der BigQuery API nicht ab. Dazu gehören unter anderem:

Fehler im Verbindungspool 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 10 Threads beschränkt, da die Standardpoolgröße für den Python HTTPAdapter 10 beträgt. Wenn Sie mehr als 10 Verbindungen verwenden möchten, erstellen Sie ein benutzerdefiniertes requests.adapters.HTTPAdapter-Objekt. Beispiel:

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)