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 클라이언트 라이브러리를 설치합니다.

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

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

쿼리 실행

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

pandas-gbq google-cloud-bigquery
기본 SQL 구문 GoogleSQL(pandas_gbq.context.dialect로 구성 가능) GoogleSQL
쿼리 구성 쿼리 요청 형식의 사전으로 전송됩니다. 다양한 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에서는 쿼리 요청 형식의 사전으로 구성을 전송해야 합니다. 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을 테이블로 로드할 수 있습니다.
구성 로드 선택적으로 테이블 스키마를 지정할 수 있습니다. 다양한 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 패키지를 설치합니다.

 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 기능을 지원하지 않습니다.

연결 풀 오류 문제 해결

오류 문자열: 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)