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

bf.options.bigquery.project를 설정하지 않으면 BigQuery Studio 및 Vertex AI 노트북을 제공하는 노트북 런타임에서 설정되는 $GOOGLE_CLOUD_PROJECT 환경 변수가 사용됩니다.

데이터 처리 위치

BigQuery DataFrames는 BigQuery 서비스에서 데이터를 유지하고 처리하는 등 확장성을 고려하여 설계되었습니다. 그러나 Series 객체 또는 DataFrame의 .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는 다음과 같은 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() only에서 지원됨
INT64 pandas.Int64Dtype()
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

  • JSON

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

bigframes.pandas 라이브러리 사용

bigframes.pandas 라이브러리는 BigQuery에서 데이터를 분석하고 조작하는 데 사용할 수 있는 pandas와 유사한 API를 제공합니다. bigframes.pandas API는 테라바이트 단위의 BigQuery 데이터 처리를 지원하도록 확장 가능하며 BigQuery 쿼리 엔진을 사용하여 계산을 수행합니다.
bigframes.pandas API는 다음과 같은 기능을 제공합니다.

입력 및 출력

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

데이터 조작

SQL 대신 Python을 사용해 개발할 수 있습니다. Python으로 모든 BigQuery 데이터 조작을 개발할 수 있으므로 언어를 전환하고 SQL 문을 텍스트 문자열로 캡처할 필요가 없습니다. bigframes.pandas API는 750개가 넘는 pandas 함수를 제공합니다.

Python 생태계 및 시각화

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

커스텀 Python 함수

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

  1. Cloud Functions(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 원격 함수는 지정한 데이터 세트 또는 코드에서 익명 데이터 세트라고 하는 특수한 유형의 숨겨진 데이터 세트에 생성됩니다. 사용자 제공 데이터 세트에서 생성된 원격 함수를 보고 관리하려면 다음을 수행합니다.

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

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

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

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

요구사항

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 Functions 함수로 배포하기 위해 불투명 상자로 직렬화됩니다.

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

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

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

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 단계를 조합할 수 있습니다. 이렇게 하면 코드가 간소화되고 데이터 사전 처리 단계와 에스티메이터를 함께 배포할 수 있습니다.

파이프라인 클래스를 사용하여 최종 에스티메이터로 변환 파이프라인을 만듭니다.

다음 단계