Scegli una libreria Python

In BigQuery puoi scegliere tra tre librerie Python, in base al tuo caso d'uso.

Caso d'uso Gestito da Descrizione
BigQuery DataFrames Elaborazione dei dati e operazioni di ML basate su Python con elaborazione lato server (ad esempio, l'utilizzo di slot) Google API Pandas e Scikit Learn implementate con pushdown lato server. Per ulteriori informazioni, consulta Introduzione a BigQuery DataFrames.
pandas-gbq Elaborazione dei dati basata su Python mediante la copia dei dati lato client Libreria open source gestita da PyData e collaboratori volontari Ti consente di spostare i dati da e verso i DataFrame di Python lato client. Per saperne di più, consulta la documentazione e il codice sorgente.
google-cloud-bigquery Deployment, amministrazione e query basate su SQL di BigQuery Libreria open source gestita da Google Pacchetto Python che racchiude tutte le API BigQuery. Per saperne di più, consulta la documentazione e il codice sorgente.

Utilizzo di pandas-gbq e google-cloud-bigquery

La libreria pandas-gbq fornisce un'interfaccia semplice per eseguire query e caricare i data frame Pandas in BigQuery. Si tratta di un wrapper sottile intorno alla libreria client BigQuery, google-cloud-bigquery. Entrambe le librerie si concentrano sull'aiutarti a eseguire analisi dei dati utilizzando SQL.

Installa le librerie

Per utilizzare gli esempi di codice in questa guida, installa il pacchetto pandas-gbq e le librerie client Python di BigQuery.

Installa i pacchetti pandas-gbq e google-cloud-bigquery.

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

Query in corso

Entrambe le librerie supportano l'esecuzione di query sui dati archiviati in BigQuery. Ecco alcune delle principali differenze tra le librerie:

pandas-gbq google-cloud-bigquery
Sintassi SQL predefinita GoogleSQL (configurabile con pandas_gbq.context.dialect) GoogleSQL
Configurazioni delle query Inviato come dizionario nel formato di una richiesta di query. Utilizza la classe QueryJobConfig, che contiene le proprietà per le varie opzioni di configurazione dell'API.

Eseguire query sui dati con la sintassi GoogleSQL

L'esempio seguente mostra come eseguire una query GoogleSQL con e senza specificare esplicitamente un progetto. Per entrambe le librerie, se non viene specificato un progetto, questo verrà determinato dalle credenziali predefinite.

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

Eseguire query sui dati con la sintassi SQL precedente

L'esempio seguente mostra come eseguire una query utilizzando la sintassi SQL precedente. Consulta la guida alla migrazione a GoogleSQL per indicazioni su come aggiornare le query in 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()

Utilizzo dell'API BigQuery Storage per scaricare risultati di grandi dimensioni

Utilizza l'API BigQuery Storage per velocizzare da 15 a 31 volte i download di risultati di grandi dimensioni.

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

Eseguire una query con una configurazione

L'invio di una configurazione con una richiesta dell'API BigQuery è necessario per eseguire determinate operazioni complesse, come l'esecuzione di una query con parametri o la specifica di una tabella di destinazione per memorizzare i risultati della query. In pandas-gbq, la configurazione deve essere inviata come dizionario nel formato di una richiesta di query. In google-cloud-bigquery sono fornite classi di configurazione dei job, come QueryJobConfig, che contengono le proprietà necessarie per configurare job complessi.

Il seguente esempio mostra come eseguire una query con parametri denominati.

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

Caricamento di un DataFrame pandas in una tabella BigQuery

Entrambe le librerie supportano il caricamento dei dati da un DataFrame pandas in una nuova tabella in BigQuery. Le differenze principali includono:

pandas-gbq google-cloud-bigquery
Supporto dei tipi Converte il DataFrame in formato CSV prima di inviarlo all'API, che non supporta valori nidificati o di array. Converte il DataFrame in formato Parquet o CSV prima di inviarlo all'API, che supporta i valori nidificati e di array. Scegli Parquet per i valori di struct e array e CSV per la flessibilità di serializzazione di date e ore. Parquet è l'opzione predefinita. Tieni presente che pyarrow, ovvero il motore Parquet utilizzato per inviare i dati del DataFrame all'API BigQuery, deve essere installato per caricare il DataFrame in una tabella.
Carica configurazioni Se vuoi, puoi specificare uno schema della tabella. Utilizza la classe LoadJobConfig, che contiene le proprietà per le varie opzioni di configurazione dell'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:

Il pacchetto google-cloud-bigquery richiede la libreria pyarrow per eseguire la serializzazione di un DataFrame Pandas in un file Parquet.

Installa il pacchetto 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()

Funzionalità non supportate da pandas-gbq

Sebbene la libreria pandas-gbq fornisca un'interfaccia utile per eseguire query sui dati e scrivere dati nelle tabelle, non copre molte delle funzionalità dell'API BigQuery, tra cui, a titolo esemplificativo:

Risolvere i problemi relativi ai pool di connessione

Stringa di errore: Connection pool is full, discarding connection: bigquery.googleapis.com. Connection pool size: 10

Se utilizzi l'oggetto client BigQuery predefinito in Python, hai un limite di massimo 10 thread perché la dimensione predefinita del pool per HTTPAdapter di Python è 10. Per utilizzare più di 10 connessioni, crea un oggetto requests.adapters.HTTPAdapter personalizzato. Ad esempio:

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)