2026년 4월 20일부터 BigLake의 이름이 Lakehouse로 변경되었습니다. BigLake metastore가 Lakehouse 런타임 카탈로그로 변경되었습니다. Lakehouse API, 클라이언트 라이브러리, CLI 명령어, IAM 이름은 변경되지 않으며 여전히 BigLake를 참조합니다.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Delta 테이블로 Spark 설정

이 문서에서는 Delta Lake 테이블을 사용하도록 Lakehouse 런타임 카탈로그로 Apache Spark를 구성하는 방법을 설명합니다. Apache Hive 카탈로그를 만들고, metastore에 연결하도록 Spark 세션을 구성하고, BigQuery에서 쿼리할 Delta 테이블을 만들고 등록하는 워크로드를 실행하는 방법을 알아봅니다.

시작하기 전에

Hive 카탈로그 엔드포인트 정보를 읽어봅니다.
지원되는 스토리지 형식 및 데이터 유형을 검토합니다.
제한사항 및 고려사항을 검토합니다.

Google Cloud 계정에 로그인합니다. 를 처음 사용하는 경우 Google Cloud 계정을 만들어 실제 시나리오에서 제품이 어떻게 작동하는지 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

Verify that billing is enabled for your Google Cloud project.

Enable the Lakehouse, Managed Service for Apache Spark APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Verify that billing is enabled for your Google Cloud project.

Enable the Lakehouse, Managed Service for Apache Spark APIs, if any are not already enabled.

Roles required to enable APIs

Enable the APIs

필요한 역할

Delta 테이블과 함께 Lakehouse 런타임 카탈로그를 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

Managed Service for Apache Spark 클러스터 만들기: Dataproc 편집자 (roles/dataproc.editor)
클러스터 서비스 계정:
- Dataproc 작업자 (roles/dataproc.worker)
- 스토리지 객체 사용자 (roles/storage.objectUser)
- BigLake 편집자 (roles/biglake.editor)
- 서비스 사용량 소비자 (roles/serviceusage.serviceUsageConsumer)
모든 Lakehouse 런타임 카탈로그 리소스에 대한 쓰기 액세스: BigLake 편집자 (roles/biglake.editor)
모든 Lakehouse 런타임 카탈로그 리소스에 대한 읽기 전용 액세스: BigLake 뷰어 (roles/biglake.viewer)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

안내는 단일 역할 부여를 참조하세요.

일반 워크플로

Delta 테이블과 함께 Lakehouse 런타임 카탈로그를 사용하려면 다음 워크플로를 따르세요.

Lakehouse Hive 카탈로그를 만듭니다.
Lakehouse 메타스토어 클라이언트 및 Delta Lake 종속 항목으로 Spark 세션을 구성합니다.
Spark를 사용하여 Cloud Storage에서 Delta 테이블을 만들고 채웁니다. 그러면 metastore에 등록됩니다.
Apache Spark (읽기 및 쓰기) 또는 BigQuery (읽기 전용)에서 직접 Delta 테이블을 쿼리합니다.

Lakehouse Hive 카탈로그 만들기

Spark 및 Delta 테이블과 함께 Lakehouse 런타임 카탈로그를 사용하려면 Hive 카탈로그를 만듭니다.

Lakehouse Hive 카탈로그는 Hive 데이터베이스 모음입니다. Spark 작업을 실행하기 전에 카탈로그를 만들어 Lakehouse Metastore에 등록합니다. 카탈로그에는 데이터의 이름과 Cloud Storage 위치가 필요합니다.

콘솔

콘솔 Google Cloud 에서 Lakehouse 페이지를 엽니다.

Lakehouse로 이동
카탈로그 만들기 를 클릭합니다.
Lakehouse 런타임 카탈로그 를 선택합니다.
카탈로그 유형에서 Hive Metastore를 선택합니다.
Cloud Storage 버킷 선택 필드에 카탈로그의 Cloud Storage 버킷 이름을 입력합니다. 또는 찾아보기 를 클릭하여 버킷을 선택하거나 만듭니다.
카탈로그 ID에 Lakehouse Hive 카탈로그의 이름을 입력합니다.
기본 위치에서 버킷과 동일한 리전을 지정합니다.
만들기 를 클릭합니다.

gcloud

Hive 카탈로그를 만들려면 다음 명령어를 실행합니다.

gcloud biglake hive catalogs create LAKEHOUSE_CATALOG_ID \
    --project=PROJECT_ID \
    --location-uri="gs://GCS_WAREHOUSE_PATH" \
    --primary-location=REGION \
    --description="DESCRIPTION"

다음을 바꿉니다.

LAKEHOUSE_CATALOG_ID: Hive 카탈로그 이름입니다.
GCS_WAREHOUSE_PATH: 웨어하우스 데이터의 Cloud Storage 경로입니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.
REGION: 메타스토어의 기본 리전입니다. 단일 리전 버킷의 경우 버킷 리전과 일치합니다. 이중 리전 또는 멀티 리전 버킷의 경우 기본 복제본의 구성 리전을 지정합니다. 다른 리전은 보조 복제본이 됩니다.
DESCRIPTION: 카탈로그에 대한 설명입니다.

Delta 테이블을 사용하도록 Spark 구성

Delta 테이블과 함께 Lakehouse 런타임 카탈로그를 사용하려면 Lakehouse metastore 클라이언트 팩터리 및 Delta Lake 확장 프로그램으로 Spark 세션을 구성합니다.

spark-sql

SSH를 사용하여 Managed Service for Apache Spark 클러스터의 기본 노드에 연결합니다.

다음 속성과 함께 명령줄에서 spark-sql을 실행하여 대화형 Spark SQL 세션을 시작합니다.

spark-sql \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=org.apache.spark.sql.delta.catalog.DeltaCatalog \
    --conf spark.hive.metastore.client.factory.class=com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory \
    --conf spark.hive.metastore.blms.project.id=PROJECT_ID \
    --conf spark.hive.metastore.blms.catalog.default=LAKEHOUSE_CATALOG_ID \
    --conf spark.hive.metastore.warehouse.dir=gs://GCS_WAREHOUSE_PATH

세션이 시작되면 Spark가 Lakehouse 런타임 카탈로그에 연결됩니다.

다음 명령어를 실행하여 Delta 리소스를 만들고 쿼리합니다.

-- Show all the databases in the current project.
SHOW DATABASES;

-- Create a database.
CREATE DATABASE spark_delta_blms_database;

-- Create a Delta data source table.
CREATE TABLE spark_delta_blms_database.delta_quick_start (id INT, name STRING) USING DELTA;

-- Insert data into the table.
INSERT INTO TABLE spark_delta_blms_database.delta_quick_start VALUES (1, 'my-first-user');

-- Query the Delta table.
SELECT * FROM spark_delta_blms_database.delta_quick_start;

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
LAKEHOUSE_CATALOG_ID: Hive 카탈로그 이름입니다.
GCS_WAREHOUSE_PATH: 웨어하우스 데이터를 저장하는 Cloud Storage 경로입니다.

Jupyter 노트북

Managed Service for Apache Spark 클러스터에서 Jupyter 노트북을 실행합니다.
Google Cloud 콘솔의 클러스터 세부정보 페이지에 있는 웹 인터페이스 탭에서 Jupyter 웹 인터페이스에 액세스합니다.

새 노트북에서 Delta Lake용으로 구성된 Spark 세션을 만들고 쿼리를 실행합니다.

from pyspark.sql import SparkSession

# If a Spark session exists, stop it first by running spark.stop()
spark = SparkSession.builder\
    .master("local")\
    .appName("Lakehouse runtime catalog Delta tutorial")\
    .config("spark.sql.extensions", "io.delta.sql.DeltaSparkSessionExtension")\
    .config("spark.sql.catalog.spark_catalog", "org.apache.spark.sql.delta.catalog.DeltaCatalog")\
    .config("spark.hive.metastore.client.factory.class", "com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory")\
    .config("spark.hive.metastore.blms.project.id", "PROJECT_ID")\
    .config("spark.hive.metastore.warehouse.dir", "gs://GCS_WAREHOUSE_PATH")\
    .config("spark.hive.metastore.blms.catalog.default", "LAKEHOUSE_CATALOG_ID")\
    .getOrCreate()

# Show all the databases.
df = spark.sql("SHOW DATABASES;")
df.show()

# Create a database.
spark.sql("CREATE DATABASE jupyter_delta_blms_db")

# Create a Delta data source table.
spark.sql("CREATE TABLE jupyter_delta_blms_db.delta_table(id INT, name STRING) USING DELTA")

# Insert data into the table.
spark.sql("INSERT INTO TABLE jupyter_delta_blms_db.delta_table VALUES (1, 'my-first-user');")

# Query from table.
spark.sql("SELECT * FROM jupyter_delta_blms_db.delta_table;").show()

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
GCS_WAREHOUSE_PATH: 웨어하우스 데이터를 저장하는 Cloud Storage 경로입니다.
LAKEHOUSE_CATALOG_ID: Hive 카탈로그 이름입니다.

BigQuery 노트북

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

BigQuery로 이동
탐색기 창에서 + 추가를 클릭한 후 Python 노트북을 클릭합니다.

코드 셀에서 Delta 확장 프로그램 및 Lakehouse 런타임 카탈로그 속성으로 Managed Service for Apache Spark 세션을 구성합니다.

from google.cloud.dataproc_spark_connect import DataprocSparkSession
from google.cloud.dataproc_v1 import Session
import os

os.environ['DATAPROC_SPARK_CONNECT_DEFAULT_DATASOURCE'] = ""

session = Session()
session.environment_config.execution_config.ttl = {"seconds": 864000}
session.runtime_config.version = "2.3"
session.runtime_config.properties = {
 "spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
 "spark.sql.catalog.spark_catalog": "org.apache.spark.sql.delta.catalog.DeltaCatalog",
 "spark.hive.metastore.blms.project.id": "PROJECT_ID",
 "spark.hive.metastore.blms.catalog.default": "LAKEHOUSE_CATALOG_ID",
 "spark.hive.metastore.warehouse.dir": "gs://GCS_WAREHOUSE_PATH",
 "spark.hive.metastore.client.factory.class": "com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory",
 "spark.sql.catalogImplementation": "hive"
}

spark = DataprocSparkSession.builder.dataprocSessionConfig(session).getOrCreate()
print("Spark session created successfully")

다른 코드 셀에서 데이터베이스와 Delta 테이블을 만듭니다.

# Create a database
spark.sql("CREATE DATABASE bq_spark_delta_database;")

# Create a Delta data source table
spark.sql("CREATE TABLE bq_spark_delta_database.delta_quick_start (id INT, name STRING) USING DELTA;")

# Insert data into the table
spark.sql("INSERT INTO TABLE bq_spark_delta_database.delta_quick_start VALUES (1, 'my-first-user');")

# Query from table
spark.sql("SELECT * FROM bq_spark_delta_database.delta_quick_start;").show()

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
GCS_WAREHOUSE_PATH: 웨어하우스 데이터를 저장하는 Cloud Storage 경로입니다.
LAKEHOUSE_CATALOG_ID: Hive 카탈로그 이름입니다.

Managed Service for Apache Spark 일괄 작업 제출

Managed Service for Apache Spark에 PySpark 일괄 워크로드를 제출하여 Lakehouse 런타임 카탈로그로 Delta 테이블을 만들고 쿼리할 수 있습니다.

PySpark 작업으로 Python 파일을 만듭니다.

from pyspark.sql import SparkSession

spark = (
    SparkSession.builder.appName("Lakehouse runtime catalog Delta tutorial")
    .config("spark.sql.extensions", "io.delta.sql.DeltaSparkSessionExtension")
    .config("spark.sql.catalog.spark_catalog", "org.apache.spark.sql.delta.catalog.DeltaCatalog")
    .config(
        "spark.hive.metastore.client.factory.class",
        "com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory",
    )
    .config("spark.hive.metastore.blms.project.id", "PROJECT_ID")
    .config("spark.hive.metastore.blms.catalog.default", "LAKEHOUSE_CATALOG_ID")
    .config(
        "spark.hive.metastore.warehouse.dir",
        "gs://GCS_WAREHOUSE_PATH",
    )
    .enableHiveSupport()
    .getOrCreate()
)

# Show all the databases.
spark.sql("SHOW DATABASES;").show()

# Create a database.
spark.sql("CREATE DATABASE dp_serverless_delta_db")

# Create a Delta data source table.
spark.sql(
    "CREATE TABLE dp_serverless_delta_db.delta_table(id INT, name STRING) USING DELTA"
)

# Insert data into the table.
spark.sql("INSERT INTO TABLE dp_serverless_delta_db.delta_table VALUES (1, 'my-first-user');")

# Query from table.
spark.sql("SELECT * FROM dp_serverless_delta_db.delta_table;").show()

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
LAKEHOUSE_CATALOG_ID: Hive 카탈로그 이름입니다.
GCS_WAREHOUSE_PATH: 웨어하우스 데이터를 저장하는 Cloud Storage 경로입니다.

일괄 작업을 제출합니다.
```
gcloud dataproc batches submit pyspark PYTHON_SCRIPT_FILE \
    --version=2.2 \
    --project=PROJECT_ID \
    --region=REGION \
    --deps-bucket=gs://CLOUD_STORAGE_BUCKET
```
다음을 바꿉니다.
- PYTHON_SCRIPT_FILE: PySpark 애플리케이션 파일의 로컬 또는 Cloud Storage 경로입니다.
- PROJECT_ID: 프로젝트 ID입니다.
- REGION: 일괄 작업을 실행할 리전입니다.
- CLOUD_STORAGE_BUCKET: 워크로드 종속 항목을 스테이징하기 위한 Cloud Storage 버킷입니다.

BigQuery에서 Delta 테이블 쿼리

Lakehouse 런타임 카탈로그에서 Spark로 Delta 테이블을 만든 후 BigQuery Studio에서 쿼리할 수 있습니다.

Hive 카탈로그 엔드포인트의 Delta 테이블에서 BigQuery로 실행되는 쿼리는 읽기 전용입니다.

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

BigQuery로 이동
쿼리 편집기에서 다음 문을 입력합니다.
```
SELECT * FROM `PROJECT_ID.LAKEHOUSE_CATALOG_ID.DATABASE_NAME.TABLE_NAME`;
```
다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID입니다.
- LAKEHOUSE_CATALOG_ID: Hive 카탈로그 이름입니다.
- DATABASE_NAME: 데이터베이스 이름입니다.
- TABLE_NAME: Delta 테이블 이름입니다.

제한사항

Lakehouse 런타임 카탈로그 Hive 카탈로그 엔드포인트와 함께 Delta 테이블을 사용하는 경우 다음 제한사항이 적용됩니다.

BigQuery의 읽기 전용 쿼리: Delta 테이블에 대한 쿼리는 BigQuery에서 읽기 전용입니다. Apache Spark를 사용하여 데이터 수정, DML 작업, 스키마 변경을 수행합니다.
GetHiveTable의 자리표시자 스키마 및 실제 스키마 검사: Delta 테이블에 대한 GetHiveTable 호출은 실제 테이블 스키마 대신 자리표시자 스키마를 반환합니다. Delta 테이블의 실제 스키마를 검사하려면 Apache Spark를 사용하세요. BigQuery는 Dremel 쿼리 실행에 맞게 수정된 스키마를 계산합니다. 이 스키마는 실제 Delta 테이블 스키마와 1:1로 일치하지 않습니다.
Hive 클라이언트 비호환성: Hive 클라이언트 (예: Hive CLI)는 Lakehouse 런타임 카탈로그 Hive 엔드포인트가 있는 Delta 테이블을 지원하지 않습니다. Apache Spark를 사용하여 Delta 테이블을 관리하고 Spark 또는 BigQuery를 사용하여 쿼리합니다.
카탈로그 관리 작업 미지원: Delta 테이블에는 카탈로그 관리 모드가 지원되지 않습니다. 독립형 메타스토어 DDL을 사용하여 Delta 테이블을 만들 수는 없습니다. 대신 Cloud Storage의 외부 스토리지 위치를 사용하여 Delta 테이블을 만들고 (예: Apache Spark 사용) 카탈로그에 등록합니다.
BigQuery 외부 Delta 테이블 제한사항: Lakehouse 런타임 카탈로그 Hive 엔드포인트는 BigQuery 외부 Delta Lake 테이블과 동일한 기본 쿼리 엔진 구현을 사용합니다. 모든 외부 Delta Lake 테이블 제한사항 및 BigLake 테이블 제한사항 이 적용됩니다. 예를 들어 변경 데이터 캡처 (CDC) 작업 및 BigQuery Storage Read API는 지원되지 않으며 timestamp_ntz는 지원되지 않습니다.

Delta 테이블로 Spark 설정 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필요한 역할

일반 워크플로

Lakehouse Hive 카탈로그 만들기

콘솔

gcloud

Delta 테이블을 사용하도록 Spark 구성

spark-sql

Jupyter 노트북

BigQuery 노트북

Managed Service for Apache Spark 일괄 작업 제출

BigQuery에서 Delta 테이블 쿼리

제한사항

다음 단계

Delta 테이블로 Spark 설정