Von pandas-gbq migrieren

Die pandas-gbq-Bibliothek ist ein Projekt der pandas-Community. Die BigQuery-Clientbibliothek google-cloud-bigquery ist die offizielle Python-Bibliothek zur Interaktion mit BigQuery. Wenn Sie die pandas-gbq-Bibliothek verwenden, nutzen Sie bereits die google-cloud-bigquery-Bibliothek. pandas-gbq sendet API-Aufrufe an BigQuery über google-cloud-bigquery.

Dieses Thema enthält Codebeispiele zum Vergleich von google-cloud-bigquery und pandas-gbq. Die Codebeispiele in diesem Thema verwenden die folgenden Bibliotheken:

google-cloud-bigquery==1.20.0
google-cloud-bigquery-storage==0.7.0
pandas==0.25.1
pandas-gbq==0.11.0
pyarrow==0.14.1

Die wichtigsten Unterschiede in Bezug auf Funktionalität und Support zwischen den beiden Bibliotheken sind:

pandas-gbq google-cloud-bigquery
Support Open-Source-Bibliothek, die von PyData und freiwilligen Contributors verwaltet wird Open-Source-Bibliothek, die von Google verwaltet wird
Abgedeckte BigQuery API-Funktionalität Beschränkt auf das Ausführen von Abfragen und das Speichern von Daten von pandas-DataFrames in Tabellen Umfassende BigQuery API-Funktionalität mit zusätzlicher Unterstützung für das Lesen/Schreiben von pandas-DataFrames und einer Jupyter-Magic zum Ausführen von Abfragen
Kadenz neuer Funktionen Neue Funktionen werden der Bibliothek nur hinzugefügt, wenn sie von freiwilligen Contributors implementiert werden Neue Features werden implementiert, wenn sie in der BigQuery API veröffentlicht werden
Dokumentation/Quellcode Dokumentation/Quellcode

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 Standard-SQL (konfigurierbar mit pandas_gbq.context.dialect) Standard-SQL
Abfragekonfiguration Wird als Wörterbuch in dem in der BigQuery-REST-Referenz angegebenen Format gesendet Verwendet die QueryJobConfig-Klasse. Sie enthält Attribute für die verschiedenen API-Konfigurationsoptionen

Daten mit der Standard-SQL-Syntax abfragen

Im folgenden Beispiel wird gezeigt, wie eine Standard-SQL-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 Standard-SQL finden Sie unter Zu Standard-SQL migrieren.

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:

import google.auth
from google.cloud import bigquery
from google.cloud import bigquery_storage_v1beta1

# Create a BigQuery client and a BigQuery Storage API client with the same
# credentials to avoid authenticating twice.
credentials, project_id = google.auth.default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)
client = bigquery.Client(credentials=credentials, project=project_id)
bqstorage_client = bigquery_storage_v1beta1.BigQueryStorageClient(
    credentials=credentials
)
sql = "SELECT * FROM `bigquery-public-data.irs_990.irs_990_2012`"

# Use a BigQuery Storage API client to download results more quickly.
df = client.query(sql).to_dataframe(bqstorage_client=bqstorage_client)

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 die Ausführung 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()

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-Format, bevor er an die API gesendet wird. Dabei werden verschachtelte und Array-Werte unterstützt. 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 Features

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: