Apache Iceberg BigLake 테이블 만들기

BigLake를 사용하면 세분화된 액세스 제어로 Iceberg 테이블에 액세스할 수 있습니다. 이렇게 하려면 먼저 Iceberg BigLake 테이블을 만들어야 합니다.

Iceberg는 페타바이트급 확장 데이터 테이블을 지원하는 오픈소스 테이블 형식입니다. Iceberg 개방형 사양을 사용하면 객체 저장소에 저장된 단일 데이터 사본에서 여러 쿼리 엔진을 실행할 수 있습니다.

BigQuery 관리자는 테이블에 데이터 마스킹을 포함한 행 및 열 수준 액세스 제어를 적용할 수 있습니다. 테이블 수준에서 액세스 제어를 설정하는 방법은 액세스 제어 정책 설정을 참조하세요. Dataproc 및 서버리스 Spark에서 BigQuery Storage API를 테이블의 데이터 소스로 사용하는 경우에도 테이블 액세스 정책이 적용됩니다. BigLake 테이블은 다른 BigQuery 서비스와의 추가 통합을 제공합니다. 사용 가능한 통합의 전체 목록은 BigLake 테이블 소개를 참조하세요.

다음과 같은 방법으로 Iceberg BigLake 테이블을 만들 수 있습니다.

• BigLake Metastore 사용(Google Cloud에 권장). BigLake Metastore는 커스텀 Iceberg 카탈로그입니다. Google Cloud에서는 Spark 워크로드와 BigQuery 워크로드 간에 테이블을 동기화할 수 있는 BigLake Metastore를 사용하는 것이 좋습니다. 이렇게 하려면 Apache Spark용 BigQuery 저장 프로시져를 사용하여 BigLake Metastore를 초기화하고 Iceberg BigLake 테이블을 만듭니다. 하지만 스키마를 업데이트하려면 BigQuery에서 업데이트 쿼리를 실행해야 합니다.

• AWS Glue Data Catalog 사용(AWS에 권장). AWS Glue는 다양한 AWS 서비스에 저장된 데이터의 구조와 위치를 정의하고 자동 스키마 검색 및 AWS 분석 도구와의 통합과 같은 기능을 제공하는 중앙 집중식 메타데이터 저장소이므로 AWS에 권장되는 방법입니다.

• Iceberg JSON 메타데이터 파일 사용(Azure에 권장) Iceberg JSON 메타데이터 파일을 사용하는 경우 테이블 업데이트가 있을 때마다 최신 메타데이터 파일을 수동으로 업데이트해야 합니다. Apache Spark용 BigQuery 저장 프러시저를 사용하여 Iceberg 메타데이터 파일을 참조하는 Iceberg BigLake 테이블을 만들 수 있습니다. 이를 방지하려면 Google Cloud용 BigLake Metastore 또는 AWS용 AWS Glue Data Catalog를 사용하면 됩니다.

  제한사항의 전체 목록은 제한사항을 참조하세요.

시작하기 전에

• Enable the BigQuery Connection, BigQuery Reservation, and BigLake APIs.

  Enable the APIs

• BigQuery의 Spark용 저장 프로시져를 사용하여 Iceberg BigLake 테이블을 만드는 경우 다음 단계를 따라야 합니다.

  1. Spark 연결을 만듭니다.
  2. 해당 연결에 대해 액세스 제어를 설정합니다.

• Iceberg BigLake 테이블 메타데이터와 데이터 파일을 Cloud Storage에 저장하려면 Cloud Storage 버킷을 만듭니다. 메타데이터 파일에 액세스하려면 Cloud Storage 버킷에 연결해야 합니다. 단계별 절차는 다음과 같습니다.

  1. 클라우드 리소스 연결을 만듭니다.
  2. 해당 연결에 대한 액세스를 설정합니다.

• BigLake Metastore를 사용하는 경우 Apache Spark에 적합한 Iceberg 커스텀 카탈로그를 설치합니다. 사용 중인 Iceberg 버전과 가장 일치하는 커스텀 카탈로그 버전을 선택합니다.

  1. Iceberg 1.5.0: gs://spark-lib/biglake/biglake-catalog-iceberg1.5.0-0.1.1-with-dependencies.jar
  2. Iceberg 1.2.0: gs://spark-lib/biglake/biglake-catalog-iceberg1.2.0-0.1.1-with-dependencies.jar
  3. Iceberg 0.14.0: gs://spark-lib/biglake/biglake-catalog-iceberg0.14.0-0.1.1-with-dependencies.jar

필요한 역할

BigLake API 호출자에게 BigLake 테이블을 만드는 데 필요한 권한을 제공하려면 관리자에게 BigLake API 호출자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

• BigQuery 관리자(roles/bigquery.admin)
• BigLake 관리자(roles/biglake.admin)

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

이러한 사전 정의된 역할에는 BigLake 테이블을 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

관리자는 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 BigLake API 호출자에게 이러한 권한을 부여할 수도 있습니다.

또한 BigQuery 사용자가 테이블을 쿼리할 수 있게 하려면 연결과 관련된 서비스 계정에 BigLake 뷰어(roles/biglake.viewer) 역할 및 해당 데이터를 포함하는 Cloud Storage 버킷에 대한 액세스 권한이 있어야 합니다.

BigLake 메타스토어를 사용하여 Iceberg BigLake 테이블을 만들려는 경우 BigLake API 호출자가 변경됩니다. Dataproc 또는 Spark 서비스 계정에 해당 데이터를 포함하는 Cloud Storage 버킷에 대한 액세스 권한을 부여해야 합니다.

• Dataproc에서 Spark를 실행할 경우 Dataproc의 호출자가 Dataproc 서비스 계정입니다.

• BigQuery에서 Spark 절차를 실행할 경우 호출자가 Spark 연결 서비스 계정입니다.

BigLake Metastore로 테이블 만들기

BigLake Metastore를 사용해서 Iceberg BigLake 테이블을 만드는 것이 좋습니다. Apache Spark를 사용하여 이러한 테이블을 만들 수 있습니다. 이를 수행하는 편리한 방법은 다음 단계에 따라 BigQuery Spark 저장 프로시져를 사용하는 것입니다.

1. BigQuery 페이지로 이동합니다.

   BigQuery로 이동

2. 탐색기 창에서 연결 리소스를 만들기 위해 사용한 프로젝트에서 연결을 클릭합니다.

3. Spark의 저장 프로시져를 만들려면 search 저장 프로시져 만들기를 클릭합니다.

4. 쿼리 편집기에서 표시되는 CREATE PROCEDURE 문을 사용하여 BigLake Metastore를 초기화하고 Iceberg BigLake 테이블을 만들기 위한 샘플 코드를 수정합니다.

    # Creates a stored procedure that initializes BLMS and database.
    # Creates a table in the database and populates a few rows of data.
    CREATE OR REPLACE PROCEDURE iceberg_demo.iceberg_setup_3_3 ()
    WITH CONNECTION `PROCEDURE_CONNECTION_PROJECT_ID.PROCEDURE_CONNECTION_REGION.PROCEDURE_CONNECTION_ID`
    OPTIONS(engine="SPARK",
    jar_uris=["gs://spark-lib/biglake/biglake-catalog-iceberg1.2.0-0.1.0-with-dependencies.jar"],
    properties=[
    ("spark.jars.packages","org.apache.iceberg:iceberg-spark-runtime-3.3_2.12:1.2.0"),
    ("spark.sql.catalog.CATALOG", "org.apache.iceberg.spark.SparkCatalog"),
    ("spark.sql.catalog.CATALOG.catalog-impl", "org.apache.iceberg.gcp.biglake.BigLakeCatalog"),
    ("spark.sql.catalog.CATALOG.hms_uri", "HMS_URI"),
    ("spark.sql.catalog.CATALOG.gcp_project", "PROJECT_ID"),
    ("spark.sql.catalog.CATALOG.gcp_location", "LOCATION"),
    ("spark.sql.catalog.CATALOG.blms_catalog", "CATALOG"),
    ("spark.sql.catalog.CATALOG.warehouse", "DATA_WAREHOUSE_URI")
    ]
    )
    LANGUAGE PYTHON AS R'''
    from pyspark.sql import SparkSession
   
    spark = SparkSession \
      .builder \
      .appName("BigLake Iceberg Example") \
      .enableHiveSupport() \
      .getOrCreate()
   
    spark.sql("CREATE NAMESPACE IF NOT EXISTS CATALOG;")
    spark.sql("CREATE DATABASE IF NOT EXISTS CATALOG.CATALOG_DB;")
    spark.sql("DROP TABLE IF EXISTS CATALOG.CATALOG_DB.CATALOG_TABLE;")
   
    # Create a BigLake Metastore table and a BigQuery Iceberg table.
    spark.sql("CREATE TABLE IF NOT EXISTS CATALOG.CATALOG_DB.CATALOG_TABLE (id bigint, demo_name string)
              USING iceberg
              TBLPROPERTIES(bq_table='BQ_DATASET.BQ_TABLE', bq_connection='TABLE_CONNECTION_PROJECT_ID.TABLE_CONNECTION_REGION.TABLE_CONNECTION_ID');
              ")
   
    # Copy a Hive Metastore table to BigLake Metastore. Can be used together with
    #   TBLPROPERTIES `bq_table` to create a BigQuery Iceberg table.
    spark.sql("CREATE TABLE CATALOG.CATALOG_DB.CATALOG_TABLE (id bigint, demo_name string)
               USING iceberg
               TBLPROPERTIES(hms_table='HMS_DB.HMS_TABLE');")
    ''';
   

   다음을 바꿉니다.

   • PROCEDURE_CONNECTION_PROJECT_ID: Spark 프로시져를 실행하기 위한 연결이 포함된 프로젝트입니다(예: myproject).

   • PROCEDURE_CONNECTION_REGION: Spark 프로시져를 실행하기 위한 연결이 포함된 리전입니다(예: us).

   • PROCEDURE_CONNECTION_ID: 연결 ID입니다(예: myconnection).

     Google Cloud 콘솔에서 연결 세부정보를 볼 때 연결 ID는 연결 ID에 표시되는 정규화된 연결 ID의 마지막 섹션에 있는 값입니다(예: projects/myproject/locations/connection_location/connections/myconnection).

   • CATALOG: BigLake Metastore에 대해 만들려는 Iceberg 카탈로그의 이름입니다.

     기본값은 iceberg입니다.

   • HMS_URI: 기존 Hive Metastore 테이블을 BigLake 메타스토어에 복사하려면 Hive 메타스토어 URI를 지정합니다.

     예를 들면 thrift://localhost:9083입니다.

   • PROJECT_ID: BigLake Metastore 인스턴스를 만들 프로젝트 ID입니다.

     Iceberg BigLake 테이블도 동일한 프로젝트에 생성됩니다.

   • LOCATION: BigLake Metastore 인스턴스를 만들 위치입니다.

     BigQuery는 동일한 위치에 저장된 BigLake Metastore 인스턴스에만 액세스할 수 있습니다.

   • DATA_WAREHOUSE_URI: Iceberg 메타데이터 및 데이터 파일을 저장하기 위해 만든 Cloud Storage 버킷 URI입니다.

     예를 들면 gs://mybucket/iceberg-warehouse입니다.

   • CATALOG_DB: BigLake Metastore에서 만들려는 데이터베이스의 이름입니다.

     이 데이터베이스는 Iceberg BigLake 테이블이 포함될 BigQuery 데이터 세트와 동일합니다.

   • CATALOG_TABLE: BigLake Metastore에 만들려는 테이블의 이름입니다.

     이 테이블은 만들려는 Iceberg BigLake 테이블과 동일합니다.

   • BQ_DATASET: Iceberg BigLake 테이블을 포함할 BigQuery 데이터 세트입니다.

   • BQ_TABLE: 만들려는 Iceberg BigLake 테이블입니다.

   • TABLE_CONNECTION_PROJECT_ID: BigLake 테이블을 만들기 위한 연결이 포함된 프로젝트입니다(예: myproject).

   • TABLE_CONNECTION_REGION: BigLake 테이블을 만들기 위한 연결이 포함된 리전입니다(예: us).

   • TABLE_CONNECTION_ID: 연결 ID입니다(예: myconnection).

     Google Cloud 콘솔에서 연결 세부정보를 볼 때 연결 ID는 연결 ID에 표시되는 정규화된 연결 ID의 마지막 섹션에 있는 값입니다(예: projects/myproject/locations/connection_location/connections/myconnection).

     BigQuery 사용자가 테이블을 쿼리할 수 있도록 하려면 연결과 관련된 서비스 계정에 roles/biglake.viewer가 있어야 합니다.

   • HMS_DB: 기존 Hive 메타스토어 테이블을 BigLake Metastore에 복사하려면 Hive 메타스토어 데이터베이스를 지정하세요.

   • HMS_TABLE: 기존 Hive Metastore 테이블을 BigLake 메타스토어에 복사하려면 Hive 메타스토어 테이블을 지정하세요.

   Iceberg 카탈로그 구성에 대한 자세한 내용은 Spark 카탈로그를 참조하세요.

5. 저장 프로시져를 실행하려면 실행을 클릭합니다. 자세한 내용은 Spark 저장 프로시져 호출을 참조하세요. Iceberg BigLake 테이블은 BigQuery에 생성됩니다.

메타데이터 파일로 테이블 만들기

JSON 메타데이터 파일로 Iceberg BigLake 테이블을 만들 수 있습니다. 하지만 이 방법은 BigLake 테이블을 최신 상태로 유지하기 위해 JSON 메타데이터 파일의 URI를 수동으로 업데이트해야 하므로 권장되는 방법은 아닙니다. URI가 최신 상태로 유지되지 않으면 BigQuery의 쿼리가 실패하거나 Iceberg 카탈로그를 직접 사용하는 다른 쿼리 엔진과 다른 결과를 제공할 수 있습니다. 이를 방지하려면 Iceberg BigLake 테이블을 만들 때 BigLake Metastore 인스턴스를 참조합니다.

Iceberg 테이블 메타데이터 파일은 Spark를 사용하여 Iceberg 테이블을 만들 때 지정하는 Cloud Storage 버킷에 생성됩니다.

다음 옵션 중 하나를 선택합니다.

  CREATE EXTERNAL TABLE myexternal-table
  WITH CONNECTION `myproject.us.myconnection`
  OPTIONS (
         format = 'ICEBERG',
         uris = ["gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json"]
   )

bq mk 

    --table 

    --external_table_definition=TABLE_FORMAT=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID 

    PROJECT_ID:DATASET.EXTERNAL_TABLE

테이블 메타데이터 업데이트

JSON 메타데이터 파일을 사용하여 Iceberg BigLake 테이블을 만드는 경우 테이블 정의를 최신 테이블 메타데이터로 업데이트합니다. 스키마 또는 메타데이터 파일을 업데이트하려면 다음 옵션 중 하나를 선택합니다.

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables/TABLE?autodetect_schema=true

{
     "externalDataConfiguration": {
      "sourceFormat": "ICEBERG",
      "sourceUris": [
        "URI"
      ]
    },
    "schema": null
  }'

액세스 제어 정책 설정

여러 가지 방법으로 BigLake 테이블에 대한 액세스를 제어할 수 있습니다.

• 열 수준 보안 설정에 대한 안내는 열 수준 보안 가이드를 참조하세요.

• 데이터 마스킹 설정에 대한 안내는 데이터 마스킹 가이드를 참조하세요.

• 행 수준 보안 설정에 대한 안내는 행 수준 보안 가이드를 참조하세요.

예를 들어 데이터 세트 mydataset의 mytable 테이블에 대한 행 액세스를 제한한다고 가정해 보겠습니다.

+---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
| JP      | tablet  |   300 |
| UK      | laptop  |   200 |
+---------+---------+-------+

김(kim@example.com)에 대해 country가 US인 행으로 액세스를 제한하는 행 수준 필터를 만들 수 있습니다.

CREATE ROW ACCESS POLICY only_us_filter
ON mydataset.mytable
GRANT TO ('user:kim@example.com')
FILTER USING (country = 'US');

그런 후 다음 쿼리를 실행합니다.

SELECT * FROM projectid.mydataset.mytable;

country가 US인 행만 출력에 표시됩니다.

+---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
+---------+---------+-------+

BigLake 테이블 쿼리

자세한 내용은 Iceberg 데이터 쿼리를 참조하세요.

데이터 매핑

BigQuery는 다음 표와 같이 Iceberg 데이터 유형을 BigQuery 데이터 유형으로 변환합니다.

제한사항

Iceberg BigLake 테이블에는 BigLake 테이블 제한사항이 포함되며 다음 제한사항도 포함됩니다.

• copy-on-write 구성이 지원되지만 merge-on-read 구성은 지원되지 않습니다. 자세한 내용은 Iceberg 구성을 참조하세요.

• BigQuery는 Bucket을 제외한 모든 Iceberg 파티션 변환 함수를 사용하여 매니페스트 프루닝을 지원합니다. 파티션을 프루닝하는 방법은 파티션을 나눈 테이블 쿼리를 참조하세요. Iceberg BigLake 테이블을 참조하는 쿼리에는 파티션을 나눈 열과 비교하여 조건자에 리터럴이 포함되어야 합니다.

• Apache Parquet 데이터 파일만 지원됩니다.

• BigLake Metastore를 사용하는 경우 다음 제한사항이 적용됩니다.

  • BigLake Metastore는 BigQuery Omni 리전에서 지원되지 않습니다.
  • 테이블 이름을 바꿀 때 대상 테이블은 소스 테이블과 동일한 데이터베이스에 있어야 합니다. 대상 테이블의 데이터베이스를 명시적으로 지정해야 합니다.
  • Iceberg 메타데이터 테이블을 조사할 때 정규화된 테이블 이름을 사용해야 합니다. 예를 들면 prod.db.table.history입니다.

비용

BigLake Metastore 요청 6,250,000건 및 BigLake Metastore에 저장된 625,000개의 객체마다 주문형(TB당) 쿼리 가격 책정에 따라 1TB 요금이 청구됩니다. 주문형 쿼리 가격 책정 비율은 리전에 따라 다릅니다. 요청 또는 객체 수가 적으면 1TB보다 적은 비율로 청구됩니다.

예를 들어 BigLake Metastore에 대해 6,250,000건의 요청을 수행하고 여기에 312,500개의 객체를 저장한 경우에는 BigLake Metastore 인스턴스를 만든 리전에 대해 주문형 쿼리 가격 책정 비율에 따라 1.5TB에 해당하는 요금이 청구됩니다.

파티션 필터 필요

Iceberg 테이블에 파티션 필터 필요 옵션을 사용 설정하여 조건자 필터를 반드시 사용하도록 지정할 수 있습니다. 이 옵션을 사용 설정할 경우 각 매니페스트 파일과 일치하는 WHERE 절을 지정하지 않고 테이블을 쿼리하려고 하면 다음 오류가 발생합니다.

Cannot query over table project_id.dataset.table without a
filter that can be used for partition elimination.

각 매니페스트 파일에는 파티션 소거에 적합한 조건자가 하나 이상 필요합니다.

Iceberg 테이블을 만드는 동안 다음과 같은 방법으로 require_partition_filter를 사용 설정할 수 있습니다.

  CREATE EXTERNAL TABLE TABLE
  WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
  OPTIONS (
         format = 'ICEBERG',
         uris = [URI],
         require_partition_filter = true
   )

bq mk \
    --table \
    --external_table_definition=ICEBERG=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID \
    PROJECT_ID:DATASET.EXTERNAL_TABLE \
    --require_partition_filter

Iceberg 테이블을 업데이트하여 파티션 필터 필요를 사용 설정할 수도 있습니다.

파티션을 나눈 테이블을 만들 때 파티션 필터 필요 옵션을 사용 설정하지 않았다면 테이블을 업데이트하여 해당 옵션을 추가할 수 있습니다.

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

다음 단계

• Spark용 저장 프로시저 알아보기
• BigLake 테이블 알아보기
• 액세스 제어 정책 설정 방법 알아보기
• BigQuery에서 쿼리 실행 알아보기
• BigQuery에서 지원되는 문 및 SQL 언어에 대해 알아보기