Choisir une bibliothèque Python

Vous avez le choix entre trois bibliothèques Python dans BigQuery, en fonction de votre cas d'utilisation.

	Cas d'utilisation	Gérée par	Description
BigQuery DataFrames	Traitement des données basé sur Python et opérations de ML avec traitement côté serveur (par exemple, utilisation d'emplacements)	Google	API pandas et scikit-learn implémentées avec pushdown côté serveur. Pour plus d'informations, consultez la page Présentation des objets BigQuery DataFrame.
pandas-gbq	Traitement des données Python à l'aide de la copie de données côté client	Bibliothèque Open Source gérée par PyData et des contributeurs bénévoles	Permet de déplacer des données vers et depuis des objets Python DataFrame côté client. Pour en savoir plus, consultez la documentation et le code source.
google-cloud-bigquery	Déploiement de BigQuery, administration et requêtes basées sur SQL	Bibliothèque Open Source gérée par Google	Package Python encapsulant toutes les API BigQuery. Pour en savoir plus, consultez la documentation et le code source.

Utiliser pandas-gbq et google-cloud-bigquery

La bibliothèque pandas-gbq fournit une interface simple pour exécuter des requêtes et importer des objets DataFrame pandas dans BigQuery. Il s'agit d'un wrapper de bas niveau autour de la bibliothèque cliente BigQuery, google-cloud-bigquery. Ces deux bibliothèques sont conçues pour vous aider à effectuer des analyses de données à l'aide de SQL.

Installer les bibliothèques

Pour utiliser les exemples de code figurant dans ce guide, installez le package pandas-gbq et les bibliothèques clientes BigQuery pour Python.

PIP

Installez les packages pandas-gbq et google-cloud-bigquery.

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

Conda

Installez les packages Conda pandas-gbq et google-cloud-bigquery à partir du canal conda-forge exploité par la communauté.

conda install -c conda-forge pandas-gbq google-cloud-bigquery

Exécution de 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	GoogleSQL (configurable avec `pandas_gbq.context.dialect`)	GoogleSQL
Configurations de requêtes	Envoyées sous forme de dictionnaire au format d'une requête.	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 une syntaxe en GoogleSQL

L'exemple ci-dessous montre comment exécuter une requête GoogleSQL 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 GoogleSQL pour savoir comment mettre à jour vos requêtes en GoogleSQL.

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 :

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

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 d'une requête. 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 ou CSV avant de l'envoyer à l'API, qui accepte les valeurs imbriquées ou de tableau. Choisissez Parquet pour les valeurs de structure et de tableau, et CSV pour la flexibilité de sérialisation des dates et heures. Parquet est le choix par défaut. 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	Vous pouvez éventuellement spécifier un schéma de table.	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

 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 :

Gestion des ensembles de données, ce qui consiste entre autres à créer des ensembles de données, à mettre à jour les propriétés associées et à supprimer des ensembles de données
Chargement des données dans BigQuery à partir de formats autres que les objets DataFrame pandas ou d'objets DataFrame pandas avec des colonnes JSON.
Gestion des tables, ce qui consiste entre autres à répertorier les tables d'un ensemble de données, à copier les données des tables et à supprimer des tables
Exportation des données BigQuery directement vers Cloud Storage

Résoudre les erreurs liées au pool de connexions

Chaîne d'erreur : Connection pool is full, discarding connection: bigquery.googleapis.com. Connection pool size: 10

Si vous utilisez l'objet client BigQuery par défaut en Python, vous êtes limité à 10 threads, car la taille du pool par défaut pour Python HTTPAdapter est définie sur 10. Pour utiliser plus de 10 connexions, créez un objet requests.adapters.HTTPAdapter personnalisé. Par exemple :

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)