BigQuery DataFrames 버전 2.0으로 마이그레이션

BigQuery DataFrames 버전 2.0에서는 BigQuery DataFrames API의 보안 및 성능이 개선되고, 새로운 기능이 추가되며, 호환성이 깨지는 변경사항이 도입됩니다. 이 문서에서는 변경사항을 설명하고 이전 안내를 제공합니다. 최신 버전 1.x의 BigQuery DataFrames를 사용하여 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 Functions에 기본적으로 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 functions의 인그레스 설정을 설정합니다. 이전에는 인그레스 설정이 기본적으로 "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)

커스텀 엔드포인트 사용

BigQuery DataFrames 버전 2.0 이전에서는 리전에서 리전 서비스 엔드포인트 및 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",
}

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

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

다음 단계