pandas-gbq에서 마이그레이션

pandas-gbq 라이브러리는 Pandas 커뮤니티에서 주도하는 프로젝트입니다. BigQuery 클라이언트 라이브러리google-cloud-bigquery는 BigQuery와 상호작용하기 위한 공식 Python 라이브러리입니다. pandas-gbq 라이브러리를 사용하는 경우 이미 google-cloud-bigquery 라이브러리를 사용하고 있는 것입니다. pandas-gbqgoogle-cloud-bigquery를 사용하여 BigQuery로 API 호출을 보내기 때문입니다.

이 주제에서는 google-cloud-bigquerypandas-gbq를 비교하는 코드 샘플을 제공합니다. 이 주제의 코드 샘플에서는 다음 라이브러리를 사용합니다.

google-cloud-bigquery==2.0.0
google-cloud-bigquery-storage==2.0.0
pandas==1.1.3
pandas-gbq==0.14.0
pyarrow==1.0.1
grpcio==1.32.0

기능 및 지원과 관련하여 두 라이브러리의 가장 큰 차이는 다음과 같습니다.

pandas-gbq google-cloud-bigquery
지원 PyData 및 자발적 재능기부자가 관리하는 오픈소스 라이브러리 Google에서 관리하는 오픈소스 라이브러리
적용되는 BigQuery API 기능 쿼리를 실행하고, 데이터를 Pandas DataFrames에서 테이블로 저장하는 기능으로 제한됩니다. Pandas DataFrames를 비롯해 쿼리 실행을 위한 Jupyter 매직을 읽고 쓸 수 있도록 추가로 지원되는 기능을 포함하여 모든 BigQuery API 기능이 제공됩니다.
새 기능이 추가되는 주기 자발적 재능기부자가 구현하는 경우에 한해 새 기능이 라이브러리에 추가됩니다. 새 기능이 BigQuery API로 배포되면서 구현됩니다.
docs/source docs/source

쿼리 실행

두 라이브러리 모두 BigQuery에 저장되는 데이터에 대한 쿼리를 지원합니다. 두 라이브러리의 가장 큰 차이점은 다음과 같습니다.

pandas-gbq google-cloud-bigquery
기본 SQL 구문 표준 SQL(pandas_gbq.context.dialect로 구성 가능) 표준 SQL
쿼리 구성 BigQuery REST 참조에 지정된 형식의 사전으로 전송됩니다. QueryJobConfig 클래스를 사용합니다. 여기에는 다양한 API 구성 옵션을 위한 속성이 포함되어 있습니다.

표준 SQL 구문을 사용한 데이터 쿼리

다음 샘플은 프로젝트를 명시적으로 지정할 때와 지정하지 않을 때 표준 SQL 쿼리를 실행하는 방법을 나타낸 것입니다. 두 라이브러리 모두 프로젝트를 지정하지 않을 경우에는 기본 사용자 인증 정보를 통해 프로젝트를 확인할 수 있습니다.

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

legacy SQL 구문을 사용한 데이터 쿼리

다음 샘플은 legacy SQL 구문을 사용하여 쿼리를 실행하는 방법을 나타낸 것입니다. 쿼리를 표준 SQL로 업데이트하는 방법에 대한 자세한 내용은 표준 SQL 마이그레이션 가이드를 참조하세요.

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

BigQuery Storage API를 사용하여 큰 결과 다운로드

BigQuery Storage API를 사용하여 큰 결과의 다운로드 속도를 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`"

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

구성을 사용한 쿼리 실행

BigQuery API 요청을 사용하여 구성을 전송하려면 매개변수화된 쿼리를 실행하거나 쿼리 결과를 저장할 대상 테이블을 지정하는 등 복잡한 작업을 수행해야 합니다. pandas-gbq에서는 BigQuery REST 참조에 지정된 형식의 사전으로 구성을 전송해야 합니다. google-cloud-bigquery에서는 복잡한 작업을 구성하는 데 필요한 속성이 포함된 작업 구성 클래스(예: QueryJobConfig)가 제공됩니다.

다음 샘플은 이름이 지정된 매개변수를 사용하여 쿼리를 실행하는 방법을 나타낸 것입니다.

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에서 BigQuery 테이블로 로드

두 라이브러리 모두 Pandas DataFrame에서 BigQuery의 새 테이블로 데이터를 업로드할 수 있는 기능을 지원합니다. 가장 큰 차이점은 다음과 같습니다.

pandas-gbq google-cloud-bigquery
지원되는 유형 API로 전송하기 전에 DataFrame을 CSV 형식으로 변환하지만 중첩 또는 배열 값을 지원하지는 않습니다. API로 전송하기 전에 DataFrame을 Parquet 형식으로 변환하며, 중첩 및 배열 값을 지원합니다. 단, DataFrame 데이터를 BigQuery API로 전송할 때 사용되는 Parquet 엔진인 pyarrow가 설치되어 있어야 DataFrame을 테이블로 로드할 수 있습니다.
구성 로드 BigQuery REST 참조에 지정된 형식의 사전으로 전송됩니다. 다양한 API 구성 옵션의 속성이 포함된 LoadJobConfig 클래스를 사용합니다.

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:

google-cloud-bigquery 패키지에는 Pandas DataFrame을 Parquet 파일로 직렬화하는 pyarrow 라이브러리가 필요합니다.

다음과 같이 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()

pandas-gbq에서 지원되지 않는 기능

pandas-gbq 라이브러리가 데이터를 쿼리하고 데이터를 테이블에 쓸 때 유용한 인터페이스를 제공하는 것은 사실이지만 아래 기능 등을 포함하여 많은 BigQuery API 기능을 지원하지 않습니다.