Open-Source-Python-Bibliotheken verwenden

Sie können Open-Source-Python-Bibliotheken in BigQuery verwenden, um Daten zu verarbeiten, Modelle für maschinelles Lernen (ML) zu erstellen und Ihre Cloud-Ressourcen mit vertrautem Code zu verwalten. Wenn Sie die richtige Bibliothek für Ihre Arbeitslast auswählen, können Sie effizient von einfachen clientseitigen Skripts bis hin zur Verarbeitung von Terabyte an Daten mit der serverseitigen BigQuery-Engine skalieren.

Bibliothek Anwendungsfall Maximale Datengröße Beschreibung
bigquery-dataframes Python-basierte Datenverarbeitung und ML-Vorgänge mit serverseitiger Verarbeitung Skalierbar auf Datasets mit mehreren Terabyte (serverseitiger Pushdown) Pandas- und scikit-learn-APIs, die mit serverseitigem Pushdown implementiert werden. Weitere Informationen finden Sie unter Einführung in BigQuery DataFrames.
pandas-gbq Python-basierte Datenverarbeitung mit clientseitiger Datenkopie Durch Client-Arbeitsspeicher eingeschränkt 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 Client-Arbeitsspeicher eingeschränkt 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 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 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 for BigQuery DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_standard_sql(project_id: str = "your-project-id") -> bpd.DataFrame:
    """Runs a standard SQL query using BigQuery DataFrames."""
    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


# Run the sample:
# df = query_standard_sql("your-project-id")
# print(df.head())

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

Mit der BigQuery Storage API können Sie das Herunterladen großer Ergebnisse um das 15- bis 31-Fache beschleunigen.

bigquery-dataframes 

import bigframes.pandas as bpd
import pandas as pd

# Set partial ordering mode for BigQuery DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_bqstorage() -> pd.DataFrame:
    """Queries BigQuery and downloads results using the BigQuery Storage API."""
    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


# Run the sample:
# pandas_df = query_bqstorage()
# print(pandas_df.head())

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 for BigQuery DataFrames.
bpd.options.bigquery.ordering_mode = "partial"


def query_parameters() -> bpd.DataFrame:
    """Queries BigQuery using BigQuery DataFrames with query parameters."""
    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


# Run the sample:
# df = query_parameters()
# print(df.head())

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 Tabelle in BigQuery. Die wichtigsten Unterschiede sind:

bigquery-dataframes pandas-gbq google-cloud-bigquery
Unterstützte Typen Konvertiert den DataFrame mit read_pandas und schreibt ihn mit to_gbq in eine 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 Arraywerte und CSV für die Flexibilität bei der Serialisierung von Datum und Uhrzeit 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 Konfigurieren Sie das Verhalten mit to_gbq-Parametern wie if_exists. 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 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:
    """Uploads an in-memory pandas DataFrame to a BigQuery table using BigQuery DataFrames."""
    # 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


# Run the sample:
# bq_df = upload_from_dataframe("your-project.your_dataset.your_table_name")
# print(bq_df.head())

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 von Daten und Schreiben von Daten in Tabellen, decken aber viele der BigQuery API-Features nicht ab, einschließlich, aber nicht beschränkt auf:

Fehlerbehebung bei Verbindungspoolfehlern

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

Wenn Sie das BigQuery-Standardclientobjekt 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)