BigQuery DataFrames 사용

BigQuery DataFrames는 BigQuery 엔진을 기반으로 하는 Pythonic DataFrame 및 머신러닝 (ML) API를 제공합니다. BigQuery DataFrames는 오픈소스 패키지입니다. pip install --upgrade bigframes를 실행하여 최신 버전을 설치할 수 있습니다.

BigQuery DataFrames는 다음과 같은 두 가지 라이브러리를 제공합니다.

  • bigframes.pandas: 분석을 위한 pandas 호환 API를 제공합니다.

  • bigframes.ml: 머신러닝 (ML)을 위한 scikit-learn 같은 API를 제공합니다.

필수 권한

옵션

설치 후에는 BigQuery DataFrames를 사용할 위치와 프로젝트를 지정해야 합니다.

다음 방법으로 노트북에서 위치와 프로젝트를 정의할 수 있습니다.

import bigframes.pandas as bpd

PROJECT_ID = "bigframes-dec"  # @param {type:"string"}
REGION = "US"  # @param {type:"string"}

# Set BigQuery DataFrames options
# Note: The project option is not required in all environments.
# On BigQuery Studio, the project ID is automatically detected.
bpd.options.bigquery.project = PROJECT_ID

# Note: The location option is not required.
# It defaults to the location of the first table or query
# passed to read_gbq(). For APIs where a location can't be
# auto-detected, the location defaults to the "US" location.
bpd.options.bigquery.location = REGION

데이터 처리 위치

BigQuery DataFrames는 BigQuery 서비스에서 데이터를 유지하고 처리하는 등 확장성을 고려하여 설계되었습니다. 그러나 DataFrame 또는 Series 객체의 .to_pandas()를 호출하여 데이터를 클라이언트 머신의 메모리로 가져올 수 있습니다. 이 경우 클라이언트 머신의 메모리 제한이 적용됩니다.

세션 위치

BigQuery DataFrames는 로컬 세션 객체를 사용하여 내부적으로 메타데이터를 관리합니다. 이 세션은 위치에 연결되어 있습니다. BigQuery DataFrames는 US 멀티 리전을 기본 위치로 사용하지만 session_options.location를 사용하여 다른 위치를 설정할 수 있습니다. 세션의 모든 쿼리는 세션이 생성된 위치에서 실행됩니다. BigQuery DataFrames는 사용자가 read_gbq/read_gbq_table/read_gbq_query()로 시작하고 직접 또는 SQL 문으로 테이블을 지정하는 경우 bf.options.bigquery.location을 테이블의 위치로 자동으로 채웁니다.

생성된 DataFrame 또는 Series 객체의 위치를 재설정하려면 bigframes.pandas.close_session()을 실행하여 세션을 닫으면 됩니다. 그런 다음 bigframes.pandas.options.bigquery.location을 다시 사용해 다른 위치를 지정할 수 있습니다.

read_gbq()에서는 쿼리하려는 데이터 세트가 US 멀티 리전에 없는 경우 위치를 지정해야 합니다. 다른 위치에서 테이블을 읽으려고 하면 NotFound 예외가 발생합니다.

BigQuery DataFrames 버전 2.0으로 이전

BigQuery DataFrames 버전 2.0에서는 BigQuery DataFrames API의 보안 및 성능을 개선하고, 새로운 기능을 추가하며, 중대한 변경사항을 도입합니다. 이 문서에서는 변경사항을 설명하고 이전 안내를 제공합니다. BigQuery DataFrames의 최신 버전 1.x를 사용하여 2.0 버전을 설치하기 전에 이러한 권장사항을 적용할 수 있습니다.

BigQuery DataFrames 버전 2.0에는 다음과 같은 이점이 있습니다.

  • allow_large_results가 기본적으로 False로 설정되어 있으므로 클라이언트에 결과를 반환하는 쿼리를 실행하면 더 빠른 쿼리와 더 적은 수의 테이블이 생성됩니다. 이렇게 하면 특히 물리적 바이트 청구를 사용하는 경우 스토리지 비용을 줄일 수 있습니다.
  • BigQuery DataFrames에서 배포된 원격 함수의 기본 보안이 개선되었습니다.

BigQuery DataFrames 버전 2.0 설치

중단을 방지하려면 requirements.txt 파일 (예: bigframes==1.42.0) 또는 pyproject.toml 파일 (예: dependencies = ["bigframes = 1.42.0"])에서 특정 버전의 BigQuery DataFrames를 고정합니다. 최신 버전을 사용해 볼 준비가 되면 pip install --upgrade bigframes를 실행하여 최신 버전의 BigQuery DataFrames를 설치할 수 있습니다.

allow_large_results 옵션 사용

BigQuery에는 쿼리 작업에 대한 최대 응답 크기 한도가 있습니다. BigQuery DataFrames 버전 2.0부터 BigQuery DataFrames는 peek(), to_pandas(), to_pandas_batches()와 같이 클라이언트에 결과를 반환하는 메서드에서 기본적으로 이 제한을 적용합니다. 작업이 큰 결과를 반환하는 경우 BigQueryOptions 객체에서 allow_large_results를 True로 설정하여 중단 변경사항을 방지할 수 있습니다. 이 옵션은 BigQuery DataFrames 버전 2.0에서 기본적으로 False로 설정됩니다.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

to_pandas() 및 다른 메서드에서 allow_large_results 매개변수를 사용하여 allow_large_results 옵션을 재정의할 수 있습니다. 예를 들면 다음과 같습니다.

bf_df = bpd.read_gbq(query)
# ... other operations on bf_df ...
pandas_df = bf_df.to_pandas(allow_large_results=True)

@remote_function 데코레이터 사용

BigQuery DataFrames 버전 2.0에서는 @remote_function 데코레이터의 기본 동작을 일부 변경합니다.

모호한 매개변수에 키워드 인수가 적용됨

의도하지 않은 매개변수에 값을 전달하지 않도록 하기 위해 BigQuery DataFrames 버전 2.0 이상에서는 다음 매개변수에 키워드 인수를 사용하도록 적용합니다.

  • bigquery_connection
  • reuse
  • name
  • packages
  • cloud_function_service_account
  • cloud_function_kms_key_name
  • cloud_function_docker_repository
  • max_batching_rows
  • cloud_function_timeout
  • cloud_function_max_instances
  • cloud_function_vpc_connector
  • cloud_function_memory_mib
  • cloud_function_ingress_settings

이러한 매개변수를 사용할 때는 매개변수 이름을 제공합니다. 예를 들면 다음과 같습니다.

@remote_function(
  name="my_remote_function",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

서비스 계정 설정

버전 2.0부터 BigQuery DataFrames는 더 이상 배포하는 Cloud Run 함수에 기본적으로 Compute Engine 서비스 계정을 사용하지 않습니다. 배포하는 함수의 권한을 제한하려면 다음 단계를 따르세요.

  1. 최소 권한으로 서비스 계정을 만듭니다.
  2. @remote_function 데코레이터의 cloud_function_service_account 매개변수에 서비스 계정 이메일을 제공합니다.

예를 들면 다음과 같습니다.

@remote_function(
  cloud_function_service_account="my-service-account@my-project.iam.gserviceaccount.com",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

Compute Engine 서비스 계정을 사용하려면 @remote_function 데코레이터의 cloud_function_service_account 매개변수를 "default"로 설정하면 됩니다. 예를 들면 다음과 같습니다.

# This usage is discouraged. Use only if you have a specific reason to use the
# default Compute Engine service account.
@remote_function(cloud_function_service_account="default", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

인그레스 설정

버전 2.0부터 BigQuery DataFrames는 "internal-only"에 배포하는 Cloud Run 함수의 인그레스 설정을 설정합니다. 이전에는 인그레스 설정이 기본적으로 "all"로 설정되었습니다. @remote_function 데코레이터의 cloud_function_ingress_settings 매개변수를 설정하여 인그레스 설정을 변경할 수 있습니다. 예를 들면 다음과 같습니다.

@remote_function(cloud_function_ingress_settings="internal-and-gclb", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

커스텀 엔드포인트 사용

2.0 미만의 BigQuery DataFrames 버전에서는 지역에서 지역 서비스 엔드포인트 및 bigframes.pandas.options.bigquery.use_regional_endpoints = True를 지원하지 않는 경우 BigQuery DataFrames가 위치 엔드포인트로 대체되었습니다. BigQuery DataFrames 버전 2.0에서는 이 대체 동작이 삭제됩니다. 버전 2.0에서 위치 엔드포인트에 연결하려면 bigframes.pandas.options.bigquery.client_endpoints_override 옵션을 설정하세요. 예를 들면 다음과 같습니다.

import bigframes.pandas as bpd

bpd.options.bigquery.client_endpoints_override = {
  "bqclient": "https://LOCATION-bigquery.googleapis.com",
  "bqconnectionclient": "LOCATION-bigqueryconnection.googleapis.com",
  "bqstoragereadclient": "LOCATION-bigquerystorage.googleapis.com",
}

LOCATION을 연결하려는 BigQuery 위치의 이름으로 바꿉니다.

bigframes.ml.llm 모듈 사용

BigQuery DataFrames 버전 2.0에서 GeminiTextGenerator의 기본 model_name가 "gemini-2.0-flash-001"로 업데이트되었습니다. 향후 기본 모델이 변경될 경우 중단을 방지하기 위해 model_name를 직접 제공하는 것이 좋습니다.

import bigframes.ml.llm

model = bigframes.ml.llm.GeminiTextGenerator(model_name="gemini-2.0-flash-001")

데이터 유형

BigQuery DataFrames는 다음과 같은 numpy 및 pandas dtype를 지원합니다.

BigQuery BigQuery DataFrames 및 pandas
ARRAY pandas.ArrowDtype(pa.list_())
BOOL pandas.BooleanDtype()
DATE pandas.ArrowDtype(pa.date32())
DATETIME pandas.ArrowDtype(pa.timestamp("us"))
FLOAT64 pandas.Float64Dtype()
GEOGRAPHY

geopandas.array.GeometryDtype()

to_pandas()에서만 지원됨
INT64 pandas.Int64Dtype()
JSON pandas 버전 3.0 이상 및 pyarrow 버전 19.0 이상에서는 pandas.ArrowDtype(pa.json_(pa.string())입니다. 그렇지 않으면 JSON 열이 pandas.ArrowDtype(db_dtypes.JSONArrowType())로 노출됩니다.
STRING pandas.StringDtype(storage="pyarrow")
STRUCT pandas.ArrowDtype(pa.struct())
TIME pandas.ArrowDtype(pa.time64("us"))
TIMESTAMP pandas.ArrowDtype(pa.timestamp("us", tz="UTC"))

BigQuery DataFrames는 다음 BigQuery 데이터 유형을 지원하지 않습니다.

  • NUMERIC

  • BIGNUMERIC

  • INTERVAL

  • RANGE

다른 모든 BigQuery 데이터 유형은 객체 유형으로 표시됩니다.

부분 순서 지정 모드

BigQuery DataFrames는 순서 지정 모드 기능을 제공합니다. ordering_mode를 partial로 설정하여 더 효율적인 쿼리를 생성합니다.

partial 순서 지정 모드는 모든 행에 대한 총 순서를 만드는 기본 strict 모드와 대조됩니다. 총 순서는 DataFrame.iloc 속성을 사용하여 행에 순서 기반 액세스를 제공하여 BigQuery DataFrames와 Pandas의 호환성을 높입니다. 그러나 총 순서와 해당 순서에 대한 기본 순차 색인을 사용하면 열 필터나 행 필터가 read_gbq 및 read_gbq_table 함수에 파라미터로 적용되지 않는 한 스캔되는 바이트 수가 줄어들지 않습니다. DataFrame의 모든 행에 대한 총 순서를 제공하기 위해 BigQuery DataFrames는 모든 행의 해시를 만듭니다. 이로 인해 행 및 열 필터를 무시하는 전체 데이터 스캔이 발생할 수 있습니다.

ordering_mode 속성을 partial로 설정하면 BigQuery DataFrame이 모든 행에 대한 총 순서를 생성하지 않습니다. 또한 부분 순서 지정 모드는 DataFrame.iloc 속성과 같이 모든 행에 대한 총 순서가 필요한 기능을 사용 중지합니다. 부분 순서 지정 모드는 DefaultIndexKind를 순서에 따른 순차 색인이 아닌 null 색인으로 설정합니다.

ordering_mode를 partial로 설정하여 DataFrame을 필터링하면 BigQuery DataFrames에서 더 이상 순차 색인에 누락된 행을 계산할 필요가 없으므로 더 빠르고 효율적인 쿼리가 생성됩니다. BigQuery DataFrames API는 엄격한 순서 지정 모드의 기본 환경과 마찬가지로 여전히 Pandas와 유사합니다. 그러나 부분 순서 지정 모드는 일반적인 Pandas 동작과 다릅니다. 예를 들어 부분 순서 지정 모드는 색인별 암시적 조인을 실행하지 않습니다.

부분 순서 지정 모드와 엄격한 순서 지정 모드 모두에서 사용한 BigQuery 리소스의 비용을 지불합니다. 그러나 클러스터 및 파티션 열의 행 필터는 처리되는 바이트 수를 줄여주므로 대규모 클러스터링된 테이블 및 파티션을 나눈 테이블을 사용할 때 부분 순서 지정 모드를 사용하면 비용을 줄일 수 있습니다.

사용

부분 순서 지정을 사용하려면 다음 코드 샘플과 같이 BigQuery DataFrames로 다른 작업을 수행하기 전에 ordering_mode를 partial로 설정하세요.

import bigframes.pandas as bpd

bpd.options.bigquery.ordering_mode = "partial"

부분 순서 지정 모드에는 순차 색인이 없으므로 관련 없는 BigQuery DataFrames는 암시적으로 조인되지 않습니다. 대신 DataFrame.merge 메서드를 명시적으로 호출하여 서로 다른 테이블 표현식에서 파생된 두 개의 BigQuery DataFrame을 조인해야 합니다.

Series.unique() 및 Series.drop_duplicates() 기능은 부분 순서 지정 모드와 호환되지 않습니다. 대신 다음과 같이 groupby 메서드를 사용하여 고유한 값을 찾습니다.

# Avoid order dependency by using groupby instead of drop_duplicates.
unique_col = df.groupby(["column"], as_index=False).size().drop(columns="size")

부분 순서 지정 모드를 사용하면 DataFrame.head(n) 및 Series.head(n) 함수의 출력이 모든 호출에서 멱등성을 가질 것이라고 보장할 수 없습니다. 임의의 소규모 데이터 샘플을 다운로드하려면 DataFrame.peek() 또는 Series.peek() 메서드를 사용하세요.

ordering_mode = "partial" 속성을 사용하는 자세한 튜토리얼은 부분 순서 지정 모드 사용을 보여주는 이 BigQuery DataFrames 노트북을 참고하세요.

문제 해결

부분 순서 지정 모드의 DataFrame에는 항상 순서 지정이나 색인이 있는 것은 아니므로 일부 pandas 호환 메서드를 사용할 때 일반적인 문제가 발생할 수 있습니다.

순서 필요 오류

일부 기능(예: DataFrame.head() 및 DataFrame.iloc 함수)에는 순서 지정이 필요합니다. 순서 지정이 필요한 기능 목록은 지원되는 Pandas API의 순서 지정 필요 열을 참고하세요.

객체에 순서가 없으면 다음과 같은 OrderRequiredError 메시지와 함께 작업이 실패합니다.

OrderRequiredError: Op iloc requires an ordering. Use .sort_values or .sort_index to provide an ordering.

오류 메시지에 설명된 대로 DataFrame.sort_values() 메서드를 사용하여 순서를 지정하면 열을 기준으로 정렬할 수 있습니다. DataFrame.groupby() 작업과 같은 다른 작업은 키별로 그룹에 대한 총 순서를 암시적으로 제공합니다.

순서 지정이 모든 행에 대해 완전히 안정적인 총 순서로 결정할 수 없는 경우 후속 작업에서 다음과 같은 AmbiguousWindowWarning 메시지로 경고를 표시할 수 있습니다.

AmbiguousWindowWarning: Window ordering may be ambiguous, this can cause unstable results.

워크로드에서 비결정론적 결과를 수용할 수 있거나 제공한 순서가 총 순서인지 수동으로 확인할 수 있는 경우 다음과 같이 AmbiguousWindowWarning 메시지를 필터링할 수 있습니다.

import warnings

import bigframes.exceptions

warnings.simplefilter(
    "ignore", category=bigframes.exceptions.AmbiguousWindowWarning
)

null 색인 오류

일부 기능(예: DataFrame.unstack() 및 Series.interpolate() 속성)에는 색인이 필요합니다.색인이 필요한 기능 목록은 지원되는 Pandas API의 색인 필요 열을 참고하세요.

부분 순서 지정 모드와 함께 색인이 필요한 작업을 사용하면 작업에서 다음과 같은 NullIndexError 메시지를 발생시킵니다.

NullIndexError: DataFrame cannot perform interpolate as it has no index. Set an index using set_index.

오류 메시지에 설명된 대로 DataFrame.set_index() 메서드를 사용하여 색일을 제공하면 열을 기준으로 정렬할 수 있습니다. DataFrame.groupby() 작업과 같은 다른 작업은 as_index=False 매개변수가 설정되지 않는 한 키별로 그룹에 대한 색인을 암시적으로 제공합니다.

bigframes.pandas 라이브러리 사용

bigframes.pandas 라이브러리는 BigQuery에서 데이터를 분석하고 조작하는 데 사용할 수 있는 pandas와 유사한 API를 제공합니다. bigframes.pandas API는 테라바이트 규모의 BigQuery 데이터 처리를 지원하도록 확장 가능하며 BigQuery 쿼리 엔진을 사용하여 계산을 실행합니다. 자세한 내용은 지원되는 pandas API를 참고하세요.

bigframes.pandas API는 다음과 같은 기능을 제공합니다.

입력 및 출력

로컬 CSV 파일, Cloud Storage 파일, pandas DataFrame, BigQuery 모델, BigQuery 함수를 비롯한 다양한 소스에서 데이터에 액세스하여 BigQuery DataFrames DataFrame에 로드할 수 있습니다. BigQuery DataFrame에서 BigQuery 테이블을 만들 수도 있습니다.

pandas와 유사한 API

BigQuery DataFrames의 주목할 만한 특징은 API가 Pandas 라이브러리의 API와 유사하도록 설계되었다는 점입니다. 이를 통해 데이터 조작 작업에 익숙한 문법 패턴을 사용할 수 있습니다. BigQuery DataFrames API를 통해 정의된 작업은 서버 측에서 실행되므로 BigQuery 내에 저장된 데이터에 직접 작동하고 BigQuery 외부로 데이터 세트를 전송할 필요가 없습니다.

API 예는 데이터 검사 및 조작을 참고하세요.

BigQuery DataFrames에서 지원되는 Pandas API를 확인하려면 지원되는 Pandas API를 참고하세요.

Python 생태계 및 시각화

bigframes.pandas API는 도구의 전체 Python 생태계로 연결되는 게이트웨이입니다. 이 API는 고급 통계 작업을 지원하며, BigQuery DataFrames에서 생성된 집계를 시각화할 수 있습니다. 샘플링 작업이 내장된 BigQuery DataFrames DataFrame에서 pandas DataFrame으로 전환할 수도 있습니다.

맞춤 Python 함수

BigQuery DataFrames를 사용하면 맞춤 스칼라 함수를 BigQuery 원격 함수로 변환할 수 있습니다 . BigQuery DataFrames에서 원격 함수를 만들면 다음이 생성됩니다.

  1. Cloud Run 함수 (2세대) 함수

  2. BigQuery 연결 기본적으로 bigframes-default-connection이라는 연결이 사용됩니다. 원하는 경우 사전 구성된 BigQuery 연결을 사용할 수 있습니다. 이 경우 연결 만들기가 생략됩니다.

    기본 연결의 서비스 계정에 Cloud Run 호출자(roles/run.invoker) IAM 역할이 부여됩니다.

  3. BigQuery 연결 (2)을 사용해 Cloud 함수 (1)를 사용하는 BigQuery 원격 함수

예를 보려면 원격 함수 만들기를 참고하세요.

BigQuery 연결은 커스텀 함수 정의에 제공한 이름을 사용하여 BigQuery DataFrames 세션과 동일한 위치에 생성됩니다. 연결을 보고 관리하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔의 BigQuery로 이동합니다.

  2. 원격 함수를 만든 프로젝트를 선택합니다.

  3. 탐색기 창에서 해당 프로젝트를 펼친 다음 외부 연결을 펼칩니다.

BigQuery 원격 함수는 지정한 데이터 세트 또는 숨겨진 데이터 세트 유형인 익명 데이터 세트에 생성됩니다. 원격 함수를 만들 때 이름을 설정하지 않으면 BigQuery DataFrames는 bigframes 접두사로 시작하는 기본 이름을 적용합니다. 사용자가 지정한 데이터 세트에서 만든 원격 함수를 보고 관리하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔의 BigQuery로 이동합니다.

  2. 원격 함수를 만든 프로젝트를 선택합니다.

  3. 탐색기 창에서 해당 프로젝트를 펼치고 원격 함수를 만든 데이터 세트를 펼친 다음 루틴을 펼칩니다.

Cloud Run 함수 함수를 보고 관리하려면 함수 페이지를 사용하고 프로젝트 선택 도구를 사용하여 함수를 만든 프로젝트를 선택합니다. BigQuery DataFrames에서 만든 함수를 식별하려면 이름에 bigframes 접두사가 있는 함수를 찾습니다.

다음과 같은 방법으로 이름이 지정되지 않은 BigQuery 원격 함수와 연결된 Cloud Run 함수 함수를 정리할 수 있습니다.

  • BigQuery DataFrames session의 경우 session.close()를 사용합니다.
  • 기본 BigQuery DataFrames 세션의 경우 bigframes.pandas.close_session()을 사용합니다.
  • session_id가 포함된 이전 세션의 경우 bigframes.pandas.clean_up_by_session_id(session_id)를 사용합니다.

요구사항

BigQuery DataFrames 원격 함수를 사용하려면 다음 API를 사용 설정해야 합니다.

BigQuery DataFrames 원격 함수를 사용하려면 프로젝트에서 다음 IAM 역할이 부여되어야 합니다.

  • BigQuery 데이터 편집자(roles/bigquery.dataEditor)

  • BigQuery 연결 관리자(roles/bigquery.connectionAdmin)

  • Cloud Functions 개발자(roles/cloudfunctions.developer)

  • 서비스 계정 사용자(roles/iam.serviceAccountUser)

  • 스토리지 객체 뷰어 (roles/storage.objectViewer)

  • 기본 BigQuery 연결을 사용하는 경우 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin) 또는 사전 구성된 연결을 사용하는 경우 브라우저(역할/브라우저). bigframes.pandas.options.bigquery.skip_bq_connection_check 옵션을 True로 설정하여 이 요구사항을 피할 수 있습니다. 이 경우 존재 또는 권한 확인 없이 연결 (기본 또는 사전 구성)을 그대로 사용합니다. 사전 구성된 연결을 사용하고 연결 확인을 건너뛰는 경우 연결이 올바른 위치에 생성되었고 프로젝트에 대한 Cloud Run 호출자(roles/run.invoker) 역할이 서비스 계정에 있는지 확인합니다.

제한사항

  • 원격 함수를 처음 만들 때는 사용할 수 있게 되기까지 약 90초가 걸립니다.

  • 노트북에 새 셀 삽입 또는 변수 이름 변경 등의 사소한 변경사항이 있는 경우 이러한 변경사항이 원격 함수 코드와 관련이 없더라도 원격 함수가 다시 생성될 수 있습니다.

  • BigQuery DataFrames는 원격 함수 코드에 포함된 개인 정보를 구별하지 않습니다. 원격 함수 코드는 불투명 상자로 직렬화되어 Cloud Run 함수 함수로 배포됩니다.

  • BigQuery DataFrames에서 만든 Cloud Run 함수 (2세대) 함수, BigQuery 연결, BigQuery 원격 함수는Google Cloud에 유지됩니다. 이러한 리소스를 유지하지 않으려면 적절한 Cloud Run 함수 또는 BigQuery 인터페이스를 사용하여 별도로 삭제해야 합니다.

  • 한 프로젝트에 Cloud Run Functions (2세대) 함수를 한 번에 최대 1,000개까지 사용할 수 있습니다. 모든 한도는 Cloud Run 함수 할당량을 참고하세요.

bigframes.pandas 예시

다음 예는 bigframes.pandas를 사용하는 일반적인 방법을 보여줍니다.

BigQuery 테이블 또는 쿼리에서 데이터 로드

다음과 같이 BigQuery 테이블 또는 쿼리에서 DataFrame을 만들 수 있습니다.

# Create a DataFrame from a BigQuery table:
import bigframes.pandas as bpd

query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

CSV 파일에서 데이터 로드

다음 방법으로 로컬 또는 Cloud Storage CSV 파일에서 DataFrame을 만들 수 있습니다.

import bigframes.pandas as bpd

filepath_or_buffer = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"
df_from_gcs = bpd.read_csv(filepath_or_buffer)
# Display the first few rows of the DataFrame:
df_from_gcs.head()

데이터 검사 및 조작

bigframes.pandas를 사용하여 데이터 검사 및 계산 작업을 수행할 수 있습니다.
다음 코드 샘플은 bigframes.pandas를 사용하여 body_mass_g 열을 검사하고 평균 body_mass를 계산하고 species별로 평균 body_mass를 계산합니다.

import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Inspect one of the columns (or series) of the DataFrame:
bq_df["body_mass_g"]

# Compute the mean of this series:
average_body_mass = bq_df["body_mass_g"].mean()
print(f"average_body_mass: {average_body_mass}")

# Find the heaviest species using the groupby operation to calculate the
# mean body_mass_g:
(
    bq_df["body_mass_g"]
    .groupby(by=bq_df["species"])
    .mean()
    .sort_values(ascending=False)
    .head(10)
)

bigframes.bigquery 라이브러리 사용

BigQuery DataFrames는 Pandas와 유사한 API 외에도 bigframes.bigquery 라이브러리를 제공합니다. 이 라이브러리는 Pandas에 상응하는 함수가 없는 많은 BigQuery SQL 함수를 제공합니다.

다음 예는 bigframes.bigquery 라이브러리를 사용하는 일반적인 방법을 보여줍니다.

배열 값 처리

bigframes.bigquery.array_agg() 함수를 사용하여 groupby 작업 후 값을 집계할 수 있습니다.

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

s = bpd.Series([0, 1, 2, 3, 4, 5])

# Group values by whether they are divisble by 2 and aggregate them into arrays
bbq.array_agg(s.groupby(s % 2 == 0))
# False    [1 3 5]
# True     [0 2 4]
# dtype: list<item: int64>[pyarrow]

array_length() 및 array_to_string() 배열 함수를 사용할 수도 있습니다.

구조체 시리즈 만들기

bigframes.bigquery.struct() 함수를 사용하여 DataFrame의 각 열에 대한 하위 필드가 있는 새 구조체 계열을 만들 수 있습니다.

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create a new STRUCT Series with subfields for each column in a DataFrames.
lengths = bbq.struct(
    bq_df[["culmen_length_mm", "culmen_depth_mm", "flipper_length_mm"]]
)

lengths.peek()
# 146	{'culmen_length_mm': 51.1, 'culmen_depth_mm': ...
# 278	{'culmen_length_mm': 48.2, 'culmen_depth_mm': ...
# 337	{'culmen_length_mm': 36.4, 'culmen_depth_mm': ...
# 154	{'culmen_length_mm': 46.5, 'culmen_depth_mm': ...
# 185	{'culmen_length_mm': 50.1, 'culmen_depth_mm': ...
# dtype: struct[pyarrow]

타임스탬프를 Unix epoch로 변환

bigframes.bigquery.unix_micros() 함수를 사용하여 타임스탬프를 Unix 마이크로초로 변환할 수 있습니다.

import pandas as pd

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Create a series that consists of three timestamps: [1970-01-01, 1970-01-02, 1970-01-03]
s = bpd.Series(pd.date_range("1970-01-01", periods=3, freq="d", tz="UTC"))

bbq.unix_micros(s)
# 0               0
# 1     86400000000
# 2    172800000000
# dtype: Int64

unix_seconds() 및 unix_millis() 시간 함수를 사용할 수도 있습니다.

SQL 스칼라 함수 사용

bigframes.bigquery.sql_scalar() 함수를 사용하여 단일 열 표현식을 나타내는 임의의 SQL 문법에 액세스합니다.

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"

# The sql_scalar function can be used to inject SQL syntax that is not supported
# or difficult to express with the bigframes.pandas APIs.
bq_df = bpd.read_gbq(query_or_table)
shortest = bbq.sql_scalar(
    "LEAST({0}, {1}, {2})",
    columns=[
        bq_df["culmen_depth_mm"],
        bq_df["culmen_length_mm"],
        bq_df["flipper_length_mm"],
    ],
)

shortest.peek()
#         0
# 149	18.9
# 33	16.3
# 296	17.2
# 287	17.0
# 307	15.0
# dtype: Float64

bigframes.ml 라이브러리 사용

BigQuery DataFrames의 ML 기능을 사용하면 데이터를 사전 처리한 후 해당 데이터로 모델을 학습할 수 있습니다. 이러한 작업을 함께 연결하여 데이터 파이프라인을 만들 수도 있습니다.

ML 위치

bigframes.ml은 BigQuery ML과 동일한 위치를 지원합니다. BigQuery ML 모델 예측 및 기타 ML 함수는 모든 BigQuery 리전에서 지원됩니다. 모델 학습 지원은 리전마다 다릅니다. 자세한 내용은 BigQuery ML 위치를 참고하세요.

데이터 사전 처리

bigframes.ml.preprocessing 모듈 및 bigframes.ml.compose 모듈을 사용하여 에스티메이터 (모델)에서 사용할 데이터를 준비할 Transformer를 만듭니다. BigQuery DataFrames는 다음과 같은 변환을 제공합니다.

  • bigframes.ml.preprocessing 모듈에서 KBinsDiscretizer 클래스를 사용하여 연속 데이터를 간격으로 비닝합니다.

  • bigframes.ml.preprocessing 모듈의 LabelEncoder 클래스를 사용하여 타겟 라벨을 정수 값으로 정규화합니다.

  • bigframes.ml.preprocessing 모듈에서 MaxAbsScaler 클래스를 사용하여 각 특성을 최대 절댓값까지 [-1, 1] 범위로 확장합니다.

  • bigframes.ml.preprocessing 모듈에서 MinMaxScaler 클래스를 사용하여 각 특성을 [0, 1] 범위로 확장하여 특성을 표준화합니다.

  • bigframes.ml.preprocessing 모듈에서 StandardScaler 클래스를 사용하여 평균을 삭제하고 단위 분산으로 확장하여 특성을 표준화합니다.

  • bigframes.ml.preprocessing 모듈에서 OneHotEncoder 클래스를 사용하여 범주형 값을 숫자 형식으로 변환합니다.

  • bigframes.ml.compose 모듈에서 ColumnTransformer 클래스를 사용하여 DataFrames 열에 Transformer를 적용합니다.

모델 학습

BigQuery DataFrames에서 모델을 학습할 추정기를 만듭니다.

클러스터링 모델

bigframes.ml.cluster 모듈을 사용하여 클러스터링 모델에 대한 에스티메이터를 만듭니다.

  • KMeans 클래스를 사용하여 K-평균 클러스터링 모델을 만듭니다. 이러한 모델은 데이터 세분화에 사용됩니다. 고객 세그먼트 식별을 예로 들 수 있습니다. k-평균은 비지도 학습 기법이므로 모델 학습에는 라벨이 필요 없으며 데이터를 학습 데이터와 평가 데이터로 분할할 필요도 없습니다.

bigframes.ml.cluster 모듈을 사용하여 클러스터링 모델에 대한 에스티메이터를 만들 수 있습니다.

다음 코드 샘플은 bigframes.ml.cluster KMeans 클래스를 사용하여 데이터 세분화를 위한 K-평균 클러스터링 모델을 만드는 방법을 보여줍니다.

from bigframes.ml.cluster import KMeans
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create the KMeans model
cluster_model = KMeans(n_clusters=10)
cluster_model.fit(bq_df["culmen_length_mm"], bq_df["sex"])

# Predict using the model
result = cluster_model.predict(bq_df)
# Score the model
score = cluster_model.score(bq_df)

분해 모델

bigframes.ml.decomposition 모듈을 사용하여 분해 모델에 대한 에스티메이터를 만듭니다.

  • PCA 클래스를 사용하여 주요 구성요소 분석 (PCA) 모델을 만듭니다. 이러한 모델을 사용하여 주성분을 계산하고 이를 사용하여 데이터에 기초하여 변경을 수행합니다. 이렇게 하면 각 데이터 포인트를 처음 몇 개의 주요 구성요소에만 투영하여 저차원 데이터를 얻고 데이터 변형을 최대한 보존하여 차원 수가 줄어듭니다.

앙상블 모델

bigframes.ml.ensemble 모듈을 사용하여 앙상블 모델에 대한 에스티메이터를 만듭니다.

  • RandomForestClassifier 클래스를 사용하여 랜덤 포레스트 분류기 모델을 만듭니다. 이 모델을 사용하여 분류를 위한 여러 학습 방법 결정 트리를 생성합니다.

  • RandomForestRegressor 클래스를 사용하여 랜덤 포레스트 회귀 모델을 만듭니다. 이 모델을 사용하여 회귀를 위한 여러 학습 방법 결정 트리를 생성합니다.

  • XGBClassifier 클래스를 사용하여 그래디언트 부스팅 트리 분류 모델을 만듭니다. 이 모델을 사용하여 분류를 위한 여러 학습 방법 결정 트리를 추가적으로 생성합니다.

  • XGBRegressor 클래스를 사용하여 그래디언트 부스팅 트리 회귀 모델을 만듭니다. 이 모델을 사용하여 회귀를 위한 여러 학습 방법 결정 트리를 추가적으로 생성합니다.

예측 모델

bigframes.ml.forecasting 모듈을 사용하여 예측 모델에 대한 에스티메이터를 만듭니다.

가져온 모델

bigframes.ml.imported 모듈을 사용하여 가져온 모델에 대한 에스티메이터를 만듭니다.

선형 모델

bigframes.ml.linear_model 모듈을 사용하여 선형 모델에 대한 에스티메이터를 만듭니다.

  • LinearRegression 클래스를 사용하여 선형 회귀 모델을 만듭니다. 이러한 모델은 예측에 사용됩니다. 예를 들어 특정 날짜의 상품 판매량을 예측하는 경우가 있습니다.

  • LogisticRegression 클래스를 사용하여 로지스틱 회귀 모델을 만듭니다. 입력이 low-value, medium-value, high-value인지 여부 등 2개 이상의 가능한 값을 분류하는 데 이러한 모델을 사용합니다.

다음 코드 샘플은 bigframes.ml을 사용하여 다음을 수행하는 방법을 보여줍니다.

from bigframes.ml.linear_model import LinearRegression
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Filter down to the data to the Adelie Penguin species
adelie_data = bq_df[bq_df.species == "Adelie Penguin (Pygoscelis adeliae)"]

# Drop the species column
adelie_data = adelie_data.drop(columns=["species"])

# Drop rows with nulls to get training data
training_data = adelie_data.dropna()

# Specify your feature (or input) columns and the label (or output) column:
feature_columns = training_data[
    ["island", "culmen_length_mm", "culmen_depth_mm", "flipper_length_mm", "sex"]
]
label_columns = training_data[["body_mass_g"]]

test_data = adelie_data[adelie_data.body_mass_g.isnull()]

# Create the linear model
model = LinearRegression()
model.fit(feature_columns, label_columns)

# Score the model
score = model.score(feature_columns, label_columns)

# Predict using the model
result = model.predict(test_data)

대규모 언어 모델

bigframes.ml.llm 모듈을 사용하여 LLM에 대한 에스티메이터를 만듭니다.

  • GeminiTextGenerator 클래스를 사용하여 Gemini 텍스트 생성기 모델을 만듭니다. 텍스트 생성 작업에 이러한 모델을 사용합니다.

  • PaLM2TextGenerator 클래스를 사용하여 PaLM2 텍스트 생성기 모델을 만듭니다. 텍스트 생성 작업에 이러한 모델을 사용합니다.

  • PaLM2TextEmbeddingGenerator 클래스를 사용하여 PaLM2 텍스트 임베딩 생성기 모델을 만듭니다. 텍스트 임베딩 생성 작업에 이러한 모델을 사용하세요.

다음을 사용할 수 있습니다.

bigframes.ml.llm 모듈을 사용하여 원격 대규모 언어 모델 (LLM)에 대한 에스티메이터를 만듭니다.
다음 코드 샘플은 bigframes.ml.llm를 사용하는 방법을 보여줍니다.

GeminiTextGenerator 클래스를 사용하여 코드 생성을 위한 Gemini 모델을 생성하는 방법을 보여줍니다.

from bigframes.ml.llm import GeminiTextGenerator
import bigframes.pandas as bpd

# Create the Gemini LLM model
session = bpd.get_global_session()
connection = f"{PROJECT_ID}.{REGION}.{CONN_NAME}"
model = GeminiTextGenerator(
    session=session, connection_name=connection, model_name="gemini-1.5-flash-002"
)

df_api = bpd.read_csv("gs://cloud-samples-data/vertex-ai/bigframe/df.csv")

# Prepare the prompts and send them to the LLM model for prediction
df_prompt_prefix = "Generate Pandas sample code for DataFrame."
df_prompt = df_prompt_prefix + df_api["API"]

# Predict using the model
df_pred = model.predict(df_prompt.to_frame(), max_output_tokens=1024)

원격 모델

BigQuery DataFrames ML 원격 모델 (bigframes.ml.remote 또는 bigframes.ml.llm)을 사용하려면 다음 API를 사용 설정해야 합니다.

또한 프로젝트에서 다음 IAM 역할을 부여 받아야 합니다.

  • BigQuery 연결 관리자(roles/bigquery.connectionAdmin)
  • 기본 BigQuery 연결을 사용하는 경우 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin) 또는 사전 구성된 연결을 사용하는 경우 브라우저(역할/브라우저). bigframes.pandas.options.bigquery.skip_bq_connection_check 옵션을 True로 설정하여 이 요구사항을 피할 수 있습니다. 이 경우 존재 또는 권한 확인 없이 연결 (기본 또는 사전 구성)을 그대로 사용합니다. 사전 구성된 연결을 사용하고 연결 확인을 건너뛰는 경우 연결이 올바른 위치에 생성되었고 프로젝트에 대한 Vertex AI 사용자(roles/aiplatform.user) 역할이 서비스 계정에 있는지 확인합니다.

BigQuery DataFrames에서 원격 모델을 만들면 BigQuery 연결이 생성됩니다. 기본적으로 bigframes-default-connection이라는 연결이 사용됩니다. 원하는 경우 사전 구성된 BigQuery 연결을 사용할 수 있습니다. 이 경우 연결 만들기가 생략됩니다. 기본 연결의 서비스 계정에 Vertex AI 사용자(roles/aiplatform.user) IAM 역할이 부여됩니다.

파이프라인 만들기

bigframes.ml.pipeline 모듈을 사용하여 ML 파이프라인을 만듭니다. 파이프라인을 사용하면 서로 다른 매개변수를 설정하여 함께 교차 검증할 여러 ML 단계를 조합할 수 있습니다. 이렇게 하면 코드가 간소화되고 데이터 사전 처리 단계와 추정기를 함께 배포할 수 있습니다.

파이프라인 클래스를 사용하여 최종 추정기로 변환 파이프라인을 만듭니다.

다음 단계