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

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

Lakehouse 런타임 카탈로그로 Spark 및 Hive 설정

Lakehouse 런타임 카탈로그를 사용하면 통합 메타데이터로 Apache Spark 및 Apache Hive 워크로드를 실행하여 BigQuery에서 테이블을 직접 쿼리할 수 있습니다. 이러한 워크로드를 관리하려면 Apache Hive 카탈로그 엔드포인트를 만들고, metastore에 연결하도록 Spark 세션을 구성하고, Spark 작업을 실행하여 쿼리 가능한 테이블을 생성합니다.

시작하기 전에

Lakehouse 런타임 카탈로그에서 Hive 카탈로그 정보를 읽고 Spark가 Lakehouse 런타임 카탈로그에 연결하는 방법을 이해합니다.
지원되는 스토리지 형식 및 데이터 유형을 검토합니다.
제한사항 및 고려사항을 검토합니다.

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $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

필요한 역할

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)

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

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

자세한 내용은 단일 역할 부여를 참조하세요.

일반 워크플로

Spark 및 Hive와 함께 Lakehouse 런타임 카탈로그를 사용하려면 다음 일반 워크플로를 따르세요.

Lakehouse Hive 카탈로그 엔드포인트를 만듭니다.
선호하는 도구 (예: Managed Service for Apache Spark 또는 BigQuery Studio)를 사용하여 Spark 세션을 구성합니다.
Spark 세션 내에서 데이터베이스 및 테이블 작업을 수행합니다.
일괄 워크로드를 Managed Service for Apache Spark에 제출하고 BigQuery에서 결과 테이블을 직접 쿼리합니다.

Lakehouse Hive 카탈로그 만들기

Spark 및 Hive와 함께 Lakehouse 런타임 카탈로그를 사용하려면 먼저 Hive 카탈로그를 만들어야 합니다.

Lakehouse Hive 카탈로그는 Hive 데이터베이스 모음입니다. Spark 작업을 실행하기 전에 카탈로그를 만들어 Lakehouse Metastore에 등록합니다. 카탈로그에는 이름과 Hive 데이터 레지던시가 있는 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: Hive 웨어하우스를 저장하는 Cloud Storage 경로
PROJECT_ID: Google Cloud프로젝트 ID
REGION: metastore의 기본 리전 단일 리전 버킷의 경우 버킷 리전과 일치해야 합니다. 이중 리전 또는 멀티 리전 버킷의 경우 구성 리전 중 하나여야 하며 metastore의 기본 복제본이 의도된 위치여야 합니다. 다른 리전은 보조 복제본이 됩니다.
DESCRIPTION: 카탈로그에 대한 설명

curl

Hive 카탈로그를 만들려면 다음 명령어를 실행하세요.

curl -X POST -s -i -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -d '{"locationUri": "gs://GCS_WAREHOUSE_PATH", "description": "DESCRIPTION"}' \
    -H "Content-Type: application/json" \
    "https://biglake.googleapis.com/hive/v1/projects/PROJECT_ID/catalogs?hiveCatalogId=LAKEHOUSE_CATALOG_ID&primary_location=REGION"

다음을 바꿉니다.

LAKEHOUSE_CATALOG_ID: Hive 카탈로그 이름
GCS_WAREHOUSE_PATH: Hive 웨어하우스를 저장하는 Cloud Storage 경로
PROJECT_ID: Google Cloud 프로젝트 ID
REGION: metastore의 기본 리전 단일 리전 버킷의 경우 버킷 리전과 일치해야 합니다. 이중 리전 또는 멀티 리전 버킷의 경우 구성 리전 중 하나여야 하며 metastore의 기본 복제본이 의도된 위치여야 합니다. 다른 리전은 보조 복제본이 됩니다.

데이터 상주 및 주권 요구사항을 위해 Hive 카탈로그 요청을 특정 리전으로 직접 라우팅하려면 리전 엔드포인트 (https://biglake.LOCATION.rep.googleapis.com)를 사용하면 됩니다.
DESCRIPTION: 카탈로그에 대한 설명

Spark 및 Hive 구성 및 사용

Lakehouse 런타임 카탈로그를 사용하려면 특정 속성으로 Spark 세션을 구성해야 합니다. Managed Service for Apache Spark 클러스터를 만들 때 이러한 속성을 설정하거나 세션을 만들 때마다 속성을 지정할 수 있습니다.

이러한 속성에는 클라이언트 팩토리, Google Cloud 프로젝트 ID, 기본 카탈로그, 웨어하우스 디렉터리와 같은 세부정보가 포함됩니다. 세션이 설정되면 기존 데이터베이스 나열, 새 데이터베이스 만들기, 테이블 정의, 데이터 삽입과 같은 기본 작업을 수행할 수 있습니다.

spark-sql

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

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

spark-sql \
    --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 런타임 카탈로그에 연결됩니다.

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


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

-- Create a database.
CREATE DATABASE spark_blms_database;

-- Create a Parquet datasource table.
CREATE TABLE spark_blms_database.parquet_quick_start (id INT, name STRING) USING PARQUET;

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

다음을 바꿉니다.

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

Jupyter 노트북

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

새 노트북에서 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 tutorial")\
    .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_blms_db")

# Create a Parquet datasource table.
spark.sql("CREATE TABLE jupyter_blms_db.parquet_table(id INT, name STRING) USING PARQUET")

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

# Query from table.
spark.sql("SELECT * FROM jupyter_blms_db.parquet_table;").show()

다음을 바꿉니다.

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

BigQuery 노트북

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

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

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

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

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

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

# Create a parquet datasource table
spark.sql("CREATE TABLE bq_spark_blms_database.parquet_quick_start (id INT, name STRING) USING PARQUET;")

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

# Query from table
spark.sql("select * from bq_spark_blms_database.parquet_quick_start;").show()

다음을 바꿉니다.

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

Hive CLI

Hive CLI를 사용하려면 metastore에 연결하도록 구성해야 합니다. 다음 두 가지 방법 중 하나로 이 작업을 수행할 수 있습니다.

옵션 1: 영구 구성. 기본 노드에서 /etc/hive/conf/hive-site.xml 파일을 업데이트합니다.
옵션 2: 임시 구성. CLI를 시작할 때 구성 플래그를 제공합니다.

CLI를 구성하고 쿼리 세션을 실행하려면 다음 단계를 따르세요.

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

구성 방법에 따라 다음 중 하나를 수행합니다.

영구적으로 구성하려면 (옵션 1):

기본 노드에서 /etc/hive/conf/hive-site.xml을 열고 다음 속성을 추가합니다.

<property>
    <name>hive.metastore.blms.project.id</name>
    <value>PROJECT_ID</value>
    <description></description>
</property>

<property>
    <name>hive.metastore.client.factory.class</name>
    <value>com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory</value>
    <description></description>
</property>
<property>
    <name>hive.metastore.blms.catalog.default</name>
    <value>LAKEHOUSE_CATALOG_ID</value>
    <description></description>
</property>
<property>
    <name>hive.metastore.warehouse.dir</name>
    <value>gs://GCS_WAREHOUSE_PATH</value>
    <description></description>
</property>

Hive CLI를 시작합니다.
```
hive
```

시작 시 일시적으로 구성하려면 (옵션 2): 구성 플래그로 Hive CLI를 시작합니다.

hive \
--hiveconf hive.metastore.blms.project.id="PROJECT_ID" \
--hiveconf hive.metastore.blms.catalog.default="LAKEHOUSE_CATALOG_ID" \
--hiveconf hive.metastore.client.factory.class=com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory \
--hiveconf hive.metastore.warehouse.dir="gs://GCS_WAREHOUSE_PATH"

그런 다음 Hive CLI 세션에서 다음 명령어를 실행합니다.
```
show databases;
create database hive_query_test;
create table hive_query_test.parquet_table (id INT, name STRING) stored as PARQUET;
select * from hive_query_test.parquet_table;
```
다음을 바꿉니다.
- PROJECT_ID: Google Cloud 프로젝트 ID
- LAKEHOUSE_CATALOG_ID: Hive 카탈로그 이름
- GCS_WAREHOUSE_PATH: Hive 웨어하우스를 저장하는 Cloud Storage 경로

Managed Service for Apache Spark 일괄 작업 제출

Lakehouse 런타임 카탈로그를 사용하는 Managed Service for Apache Spark에 PySpark 일괄 워크로드를 제출할 수 있습니다.

이 PySpark 스니펫은 Lakehouse 런타임 카탈로그에 연결하도록 구성된 Spark 세션을 초기화합니다. Lakehouse 클라이언트 팩토리, Google Cloud 프로젝트 ID, 기본 카탈로그, 웨어하우스 디렉터리와 같은 필수 속성을 설정합니다. 세션을 설정한 후에는 Spark SQL 명령어를 사용하여 기존 데이터베이스를 나열하고, 새 데이터베이스를 만들고, 해당 데이터베이스 내에서 Parquet 형식 테이블을 정의하는 방법을 보여줍니다.

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

from pyspark.sql import SparkSession

spark = (
    SparkSession.builder.appName("Lakehouse runtime catalog tutorial")
    .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_test")

# Create a Parquet datasource table.
spark.sql(
        "CREATE TABLE dp_serverless_test.parquet_table(id INT, name STRING) USING"
        " PARQUET"
    )

# Query from table.
spark.sql("SELECT * from  dp_serverless_test.parquet_table").show()

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID
LAKEHOUSE_CATALOG_ID: Hive 카탈로그 이름
GCS_WAREHOUSE_PATH: Hive 웨어하우스를 저장하는 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에서 테이블 쿼리

Lakehouse 런타임 카탈로그에서 Spark로 리소스를 만든 후 BigQuery Studio에서 쿼리할 수 있습니다.

콘솔 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: 테이블 이름입니다.

Lakehouse 런타임 카탈로그로 Spark 및 Hive 설정 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

필요한 역할

일반 워크플로

Lakehouse Hive 카탈로그 만들기

콘솔

gcloud

curl

Spark 및 Hive 구성 및 사용

spark-sql

Jupyter 노트북

BigQuery 노트북

Hive CLI

Managed Service for Apache Spark 일괄 작업 제출

BigQuery에서 테이블 쿼리

Lakehouse 런타임 카탈로그로 Spark 및 Hive 설정