Migrer depuis pandas-gbq

La bibliothèque pandas-gbq est un projet mené par la communauté pandas. La bibliothèque cliente BigQuery, google-cloud-bigquery, est la bibliothèque Python officielle utilisée pour les interactions avec BigQuery. Si vous vous servez de pandas-gbq, vous êtes déjà familiarisé avec google-cloud-bigquery. En effet, la bibliothèque pandas-gbq utilise google-cloud-bigquery pour effectuer des appels d'API vers BigQuery.

Cette rubrique fournit des exemples de code comparant google-cloud-bigquery et pandas-gbq. Ces exemples utilisent les bibliothèques suivantes :

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

Les principales différences qui existent en termes de fonctionnalités et d'assistance entre les deux bibliothèques sont décrites ci-dessous.

pandas-gbq google-cloud-bigquery
Assistance Bibliothèque Open Source gérée par PyData et des contributeurs bénévoles Bibliothèque Open Source gérée par Google
Fonctionnalités de l'API BigQuery fournies Fonctionnalités limitées à l'exécution de requêtes et à l'enregistrement des données des objets DataFrame pandas dans des tables. Fonctionnalités complètes de l'API BigQuery avec la possibilité d'effectuer des opérations de lecture/écriture sur les objets DataFrame pandas et d'utiliser une commande magique Jupyter pour l'exécution des requêtes.
Fréquence des nouvelles fonctionnalités De nouvelles fonctionnalités ne sont ajoutées à la bibliothèque que si des contributeurs volontaires les mettent en œuvre. Les nouvelles fonctionnalités sont mises en œuvre dès qu'elles sont disponibles dans l'API BigQuery.
docs/source docs/source

Exécuter des requêtes

Les deux bibliothèques permettent d'interroger les données stockées dans BigQuery. Les principales différences qui les distinguent sont présentées ci-dessous.

pandas-gbq google-cloud-bigquery
Syntaxe SQL par défaut SQL standard (configurable avec pandas_gbq.context.dialect) SQL standard
Configurations de requêtes Envoyées sous forme de dictionnaire au format spécifié dans la documentation de référence de l'API REST BigQuery. Possibilité d'utiliser la classe QueryJobConfig, qui contient les propriétés des différentes options de configuration de l'API.

Interroger des données avec la syntaxe SQL standard

L'exemple ci-dessous montre comment exécuter une requête SQL standard en indiquant de façon explicite un projet ou sans le spécifier. Pour les deux bibliothèques, si vous ne spécifiez aucun projet, il sera déterminé à partir des identifiants par défaut.

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

Interroger des données avec une syntaxe en ancien SQL

L'exemple ci-dessous montre comment exécuter une requête à l'aide d'une syntaxe en ancien SQL. Consultez le guide de migration vers le langage SQL standard pour savoir comment mettre à jour vos requêtes en SQL standard.

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

Télécharger des résultats volumineux à l'aide de l'API BigQuery Storage

L'API BigQuery Storage vous permet de multiplier la vitesse de téléchargement des résultats volumineux par 15 à 31.

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)

Exécuter une requête avec une configuration

L'envoi d'une configuration avec une requête d'API BigQuery est nécessaire pour effectuer certaines opérations complexes, telles que l'exécution d'une requête paramétrée ou la spécification d'une table de destination permettant de stocker les résultats de requête. Dans pandas-gbq, la configuration doit être envoyée sous forme de dictionnaire au format spécifié dans la documentation de référence REST de BigQuery. google-cloud-bigquery fournit des classes de configuration de tâche telles que QueryJobConfig, qui contiennent les propriétés nécessaires à la configuration de tâches complexes.

L'exemple ci-dessous montre comment exécuter une requête avec des paramètres nommés.

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

Charger un objet DataFrame pandas dans une table BigQuery

Les deux bibliothèques permettent d'importer les données d'un objet DataFrame pandas dans une nouvelle table BigQuery. Les principales différences qui les distinguent sont décrites ci-dessous.

pandas-gbq google-cloud-bigquery
Formats compatibles Convertit l'objet DataFrame au format CSV avant de l'envoyer à l'API, qui n'accepte pas les valeurs imbriquées ou de tableau. Convertit l'objet DataFrame au format Parquet avant de l'envoyer à l'API, qui accepte les valeurs imbriquées ou de tableau. Notez que pyarrow, qui est le moteur Parquet utilisé pour envoyer les données DataFrame à l'API BigQuery, doit être installé pour permettre le chargement de l'objet DataFrame dans une table.
Configurations de chargement Envoyées sous forme de dictionnaire au format spécifié dans la documentation de référence de l'API REST BigQuery. Possibilité d'utiliser la classe LoadJobConfig, qui contient les propriétés des différentes options de configuration de l'API.

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 :

Le package google-cloud-bigquery nécessite la bibliothèque pyarrow pour sérialiser un objet DataFrame pandas en fichier Parquet.

Installez le package pyarrow :

 conda install -c conda-forge pyarrow

ou

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

Fonctionnalités non disponibles avec pandas-gbq

Même si la bibliothèque pandas-gbq fournit une interface utile pour interroger et écrire des données dans des tables, il lui manque de nombreuses fonctionnalités offertes par l'API BigQuery, parmi lesquelles :