Python 라이브러리 선택

사용 사례에 따라 BigQuery의 Python 라이브러리 3개 중에서 선택할 수 있습니다.

	사용 사례	유지보수 담당자	설명
BigQuery DataFrames	Python 기반 데이터 처리 및 서버 측 처리가 포함된 ML 작업(예: 슬롯 사용)	Google	Pandas 및 Scikit는 서버 측 푸시다운으로 구현된 API를 학습합니다. 자세한 내용은 BigQuery DataFrames 소개를 참조하세요.
pandas-gbq	클라이언트 측 데이터 복사를 사용한 Python 기반 데이터 처리	PyData 및 자발적 재능기부자가 관리하는 오픈소스 라이브러리	클라이언트 측에서 Python DataFrames와 데이터를 주고받을 수 있습니다. 자세한 내용은 문서 및 소스 코드를 참조하세요.
google-cloud-bigquery	BigQuery 배포, 관리, SQL 기반 쿼리	Google에서 관리하는 오픈소스 라이브러리	모든 BigQuery API를 래핑하는 Python 패키지입니다. 자세한 내용은 문서 및 소스 코드를 참조하세요.

pandas-gbq 및 google-cloud-bigquery 사용

pandas-gbq 라이브러리에서는 쿼리를 실행하고 Pandas DataFrame을 BigQuery에 업로드할 수 있는 간단한 인터페이스를 제공합니다. BigQuery 클라이언트 라이브러리 google-cloud-bigquery의 씬 래퍼입니다. 이러한 두 라이브러리 모두 사용하면 SQL을 사용하여 데이터 분석을 수행할 수 있습니다.

라이브러리 설치

이 가이드의 코드 샘플을 사용하려면 pandas-gbq 패키지와 BigQuery Python 클라이언트 라이브러리를 설치합니다.

PIP

pandas-gbq 및 google-cloud-bigquery 패키지를 설치합니다.

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

Conda

커뮤니티에서 운영하는 conda-forge 채널에서 pandas-gbq 및 google-cloud-bigquery Conda 패키지를 설치합니다.

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

쿼리 실행 중

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

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

GoogleSQL 구문을 사용한 데이터 쿼리

다음 샘플에서는 프로젝트의 명시적 지정 여부에 따라 GoogleSQL 쿼리를 실행하는 방법을 보여줍니다. 두 라이브러리 모두 프로젝트를 지정하지 않을 경우에는 기본 사용자 인증 정보를 통해 프로젝트를 확인할 수 있습니다.

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

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

다음 샘플은 이전 SQL 구문을 사용하여 쿼리를 실행하는 방법을 나타낸 것입니다. 쿼리를 GoogleSQL로 업데이트하는 방법에 대한 자세한 내용은 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()

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`"

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

구성을 사용한 쿼리 실행

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 또는 CSV 형식으로 변환하며 중첩 및 배열 값을 지원합니다. 구조체 및 배열 값에 Parquet를 선택하고 날짜 및 시간 직렬화 유연성을 위해 CSV를 선택합니다. 기본적으로 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 기능을 지원하지 않습니다.

새 데이터세트 만들기, 데이터세트 속성 업데이트, 데이터세트 삭제를 포함한 데이터세트 관리
Pandas DataFrames가 아닌 다른 형식에서 BigQuery로 데이터 로드
데이터세트의 테이블 나열, 테이블 데이터 복사, 테이블 삭제를 포함한 테이블 관리
Cloud Storage로 직접 BigQuery 데이터 내보내기

연결 풀 오류 문제 해결

오류 문자열: Connection pool is full, discarding connection: bigquery.googleapis.com. Connection pool size: 10

Python에서 기본 BigQuery 클라이언트 객체를 사용하는 경우 Python HTTPAdapter의 기본 풀 크기가 10이므로 스레드 수는 최대 10개로 제한됩니다. 10개 이상의 연결을 사용하려면 커스텀 requests.adapters.HTTPAdapter 객체를 만듭니다. 예를 들면 다음과 같습니다.

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)