Open-Source-Python-Bibliotheken verwenden

Je nach Anwendungsfall können Sie aus drei Python-Bibliotheken in BigQuery auswä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 Clientspeicher begrenzt Ermöglicht das Verschieben von Daten in und aus Python-DataFrames auf der Clientseite. Weitere Informationen finden Sie in der Dokumentation und im Quellcode.
google-cloud-bigquery BigQuery-Bereitstellung, ‑Administration und SQL-basierte Abfragen Durch 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 BigQuery DataFrames-Bibliothek (bigframes) bietet eine Pythonic DataFrame- und ML-API mit serverseitiger Abfrageverarbeitung. 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.

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 den Parametern bpd.options.bigquery oder read_gbq Wird als Dictionary 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 keine Legacy-SQL-Syntax. 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 Dictionary 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

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

bigquery-dataframes pandas-gbq google-cloud-bigquery
Unterstützte Typen Konvertiert den lokalen Pandas-DataFrame mithilfe von read_pandas in ein bigframes.pandas.DataFrame (unter der Haube wird Parquet oder CSV verwendet). Dabei werden verschachtelte und Array-Werte unterstützt. Anschließend speichern Sie sie mit to_gbq in einer Tabelle. 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 flexible 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 Verwenden Sie den Parameter if_exists ('fail', 'replace' oder 'append'), wenn Sie mit to_gbq speichern. Optional können Sie ein Tabellenschema angeben. Verwendet die Klasse LoadJobConfig. Sie enthält Attribute für die verschiedenen API-Konfigurationsoptionen.

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 upload_from_dataframe(
    table_id: str = "your-project.your_dataset.your_table_name",
) -> bpd.DataFrame:
    # Create a local pandas DataFrame.
    df = pd.DataFrame(
        {
            "my_string": ["a", "b", "c"],
            "my_int64": [1, 2, 3],
            "my_float64": [4.0, 5.0, 6.0],
        }
    )

    # Convert the local pandas DataFrame to a BigQuery DataFrame.
    bq_df = bpd.read_pandas(df)

    # Write the DataFrame to a BigQuery table.
    bq_df.to_gbq(table_id, if_exists="replace")
    return bq_df

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 ist. 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)