Menggunakan library Python open source

Anda dapat menggunakan library Python open source di BigQuery untuk memproses data, membangun model machine learning (ML), dan mengelola resource cloud menggunakan kode yang sudah dikenal. Memilih library yang tepat untuk workload dapat membantu Anda menskalakan secara efisien dari skrip sisi klien yang ringan hingga memproses data berukuran terabyte menggunakan mesin sisi server BigQuery.

Library Kasus penggunaan Ukuran data maksimum Deskripsi
bigquery-dataframes Pemrosesan data dan operasi ML berbasis Python dengan pemrosesan sisi server Dapat diskalakan ke set data multi-terabyte (pushdown sisi server) API Pandas dan scikit-learn yang diimplementasikan dengan pushdown sisi server. Untuk mengetahui informasi selengkapnya, lihat Pengantar BigQuery DataFrames.
pandas-gbq Pemrosesan data berbasis Python menggunakan salinan data sisi klien Dibatasi oleh memori klien Memungkinkan Anda memindahkan data ke dan dari DataFrame Python di sisi klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi dan kode sumber.
google-cloud-bigquery Deployment, administrasi, dan pembuatan kueri berbasis SQL BigQuery Dibatasi oleh memori klien Paket Python yang menggabungkan semua BigQuery API. Untuk mengetahui informasi selengkapnya, lihat dokumentasi dan kode sumber.

Menggunakan BigQuery DataFrames, pandas-gbq, dan google-cloud-bigquery

Library BigQuery DataFrames (bigframes) menyediakan DataFrame dan ML API pythonic dengan pemrosesan kueri sisi server. Library pandas-gbq menyediakan antarmuka untuk menjalankan kueri dan mengupload DataFrame pandas ke BigQuery. Library ini adalah wrapper tipis di sekitar library klien BigQuery, google-cloud-bigquery.

Menginstal library

Untuk menggunakan contoh kode dalam panduan ini, instal paket bigframes, pandas-gbq, dan google-cloud-bigquery:

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

Menjalankan Kueri

Ketiga library mendukung pembuatan kueri data yang tersimpan di BigQuery. Perbedaan utama antar-library meliputi:

bigquery-dataframes pandas-gbq google-cloud-bigquery
Sintaksis SQL default GoogleSQL GoogleSQL (dapat dikonfigurasi dengan pandas_gbq.context.dialect) GoogleSQL
Konfigurasi kueri Dapat dikonfigurasi menggunakan parameter bpd.options.bigquery atau read_gbq Dikirim sebagai kamus dalam format permintaan kueri. Gunakan class QueryJobConfig, yang berisi properti untuk berbagai opsi konfigurasi API.

Membuat kueri data dengan sintaks GoogleSQL

Contoh berikut menunjukkan cara menjalankan kueri GoogleSQL dengan dan tanpa menentukan project secara eksplisit. Untuk ketiga library, jika project tidak ditentukan, project akan ditentukan dari kredensial default.

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

Membuat kueri data dengan sintaksis legacy SQL

Contoh berikut menunjukkan cara menjalankan kueri menggunakan sintaksis legacy SQL. Lihat panduan migrasi GoogleSQL untuk mendapatkan panduan tentang cara memperbarui kueri ke GoogleSQL.

bigquery-dataframes

BigQuery DataFrames tidak mendukung sintaksis legacy SQL. Gunakan sintaksis 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()

Menggunakan BigQuery Storage API untuk mendownload hasil dalam jumlah besar

Gunakan BigQuery Storage API untuk mempercepat download hasil besar sebanyak 15 hingga 31 kali.

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

Menjalankan kueri dengan konfigurasi

Pengiriman konfigurasi dengan permintaan BigQuery API diperlukan untuk melakukan operasi kompleks tertentu, seperti menjalankan kueri berparameter atau menentukan tabel tujuan untuk menyimpan hasil kueri. Di bigquery-dataframes (read_gbq) dan pandas-gbq, konfigurasi harus dikirim sebagai kamus dalam format permintaan kueri. Di google-cloud-bigquery, class konfigurasi tugas disediakan, seperti QueryJobConfig, yang berisi properti yang diperlukan untuk mengonfigurasi tugas yang kompleks.

Contoh berikut menunjukkan cara menjalankan kueri dengan parameter bernama.

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

Memuat DataFrame pandas ke tabel BigQuery

Ketiga library mendukung upload data dari DataFrame pandas ke tabel baru di BigQuery. Perbedaan utamanya meliputi:

bigquery-dataframes pandas-gbq google-cloud-bigquery
Dukungan jenis Mengonversi DataFrame menggunakan read_pandas dan menulisnya ke tabel menggunakan to_gbq. Mengonversi DataFrame menjadi format CSV sebelum mengirim ke API, yang tidak mendukung nilai susun bertingkat atau array. Mengonversi DataFrame ke format Parquet atau CSV sebelum mengirim ke API, yang mendukung nilai bertingkat dan array. Pilih Parquet untuk nilai struct dan array, serta CSV untuk fleksibilitas serialisasi tanggal dan waktu. Parquet adalah pilihan default. Perhatikan bahwa pyarrow, yang merupakan mesin parquet yang digunakan untuk mengirim data DataFrame ke BigQuery API, harus diinstal untuk memuat DataFrame ke tabel.
Memuat konfigurasi Konfigurasikan perilaku dengan parameter to_gbq, seperti if_exists. Anda juga dapat menentukan skema tabel. Gunakan class LoadJobConfig, yang berisi properti untuk berbagai opsi konfigurasi API.

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

Paket google-cloud-bigquery memerlukan library pyarrow untuk melakukan serialisasi pandas DataFrame ke file Parquet.

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

Fitur yang tidak didukung oleh pandas-gbq dan bigquery-dataframes

Meskipun library pandas-gbq dan bigquery-dataframes menyediakan antarmuka yang berguna untuk membuat kueri data dan menulis data ke tabel, library ini tidak mencakup banyak fitur BigQuery API, termasuk, tetapi tidak terbatas pada:

Memecahkan masalah error kumpulan koneksi

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

Jika menggunakan objek klien BigQuery default di Python, Anda dibatasi hingga maksimum 10 thread karena ukuran kumpulan default untuk HTTPAdapter Python adalah 10. Untuk menggunakan lebih dari 10 koneksi, buat objek requests.adapters.HTTPAdapter kustom. Contoh:

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)