외부 관리형 |iceberg-tm|테이블에 대한 쓰기 지원¶

고려 사항¶

외부 관리형 Iceberg 테이블에 대한 쓰기 지원을 사용하는 경우 다음 사항을 고려합니다.

• Snowflake는 외부 관리형 테이블에 대한 데이터 정의 언어(DDL) 및 데이터 조작 언어(DML) 명령을 제공합니다. 그러나 외부 카탈로그와 외부 저장소 공급자가 제공하는 도구를 사용하여 메타데이터 및 데이터 보존을 구성합니다. 자세한 내용은 외부 카탈로그를 사용하는 테이블 섹션을 참조하십시오.

  쓰기의 경우 Snowflake는 Snowflake에서 테이블을 업데이트하기 전에 원격 카탈로그에 변경 사항이 커밋되었는지 확인합니다.

• 카탈로그 연결 데이터베이스를 사용하는 경우 열 정의와 함께 CREATE ICEBERG TABLE 구문을 사용하여 Snowflake 및 원격 카탈로그에 테이블을 만들 수 있습니다. (카탈로그에 연결되지 않은) 표준 Snowflake 데이터베이스를 사용하는 경우 먼저 원격 카탈로그에 테이블을 생성해야 합니다. 그 후에는 CREATE ICEBERG TABLE(Iceberg REST 카탈로그) 구문을 사용하여 Snowflake에서 Iceberg 테이블을 만들고 테이블에 작성합니다.

• AWS Glue 데이터 카탈로그의 경우: Snowflake를 통해 외부 관리 테이블을 삭제해도 기본 테이블 파일은 삭제되지 않습니다. 이 동작은 AWS Glue 데이터 카탈로그 구현에만 해당됩니다.

• 이 기능의 비공개 미리 보기에 참여한 경우 계정에서 기본적으로 위치 행 수준 삭제가 활성화될 수 있습니다. 확인하려면 다음 명령을 실행합니다.

  SHOW PARAMETERS LIKE 'ENABLE_ICEBERG_MERGE_ON_READ' IN ACCOUNT;
  

  Copy

  매개 변수가 계정에 표시되면(값에 관계없이) 위치 삭제가 활성화됩니다. 위치 삭제를 끄려면 테이블, 스키마 또는 데이터베이스 수준에서 ENABLE_ICEBERG_MERGE_ON_READ 매개 변수를 FALSE로 설정합니다.

• 다음과 같은 Iceberg 데이터 타입을 사용한 외부 관리형 테이블에 대한 작성은 지원되지 않습니다.

  • uuid

  • fixed(L)

• 현재 다음 기능은 Snowflake를 사용하여 외부 관리형 Iceberg 테이블에 작성하는 경우 지원되지 않습니다.

  • 카탈로그 발급 자격 증명.

  • GCS또는 Azure 외부 볼륨에 대한 서버 측 암호화(SSE).

  • 다중 문 트랜잭션. Snowflake는 자동 커밋 트랜잭션만 지원합니다.

  • Snowflake 관리형 테이블로의 변환.

  • Iceberg REST 프로토콜을 준수하지 않는 외부 Iceberg 카탈로그.

  • 행 수준 삭제(읽을 때 병합).

  • 테이블을 생성할 때 OR REPLACE 옵션 사용.

  • AWS Glue를 원격 카탈로그로 사용하는 경우 CREATE TABLE … AS SELECT 구문 사용.

• 카탈로그 연결 데이터베이스에서 스키마를 생성할 때 다음 사항에 유의합니다.

  • CREATE SCHEMA 명령은 카탈로그 연결 데이터베이스를 사용할 때만 원격 카탈로그에 해당 네임스페이스를 생성합니다.

  • ALTER 및 CLONE 옵션은 지원되지 않습니다.

  • 스키마 이름에는 구분 기호가 지원되지 않습니다. 영숫자 스키마 이름만 지원됩니다.

• 테이블의 Parquet 파일에 대한 대상 파일 크기를 설정할 수 있습니다. 자세한 내용은 대상 파일 크기 설정하기 섹션을 참조하십시오.

워크플로¶

이 기능을 시작하려면 이 섹션의 워크플로를 사용합니다.

1. 외부 볼륨 구성

2. 카탈로그 통합 만들기

3. 다음 옵션 중에서 선택합니다.

   • 카탈로그 연결 데이터베이스 만들기. 이 옵션을 사용하면 카탈로그에서 자동으로 검색된 Iceberg 테이블에 작성하거나 카탈로그 연결 데이터베이스를 사용하여 추가 Iceberg 테이블을 생성할 수 있습니다.

   • :ref:`Iceberg 테이블 만들기<label-tables_iceberg_external_writes_create_table>`(카탈로그 연결 데이터베이스 또는 표준 Snowflake 데이터베이스에서). 이 옵션을 사용하면 Snowflake에서 외부 관리형 Iceberg 테이블을 만들기 전에 먼저 원격 카탈로그에 테이블을 만들어야 합니다.

이러한 단계를 완료한 후에는 Iceberg 테이블에 대한 :ref:`쓰기 작업<label-tables_iceberg_externally_managed_write_operations>`을 수행할 수 있습니다.

외부 관리형 테이블에 쓰기를 위한 외부 볼륨 구성하기¶

외부 관리형 테이블에 대한 쓰기를 활성화하려면 Snowflake 서비스 주체에 대한 읽기 및 쓰기 권한(Snowflake 관리형 테이블에 필요한 권한과 동일한 권한)으로 구성된 외부 볼륨을 사용해야 합니다.

Iceberg REST 카탈로그가 Iceberg 데이터와 메타데이터를 작성하는 저장 위치(STORAGE_BASE_URL)를 지정합니다.

예를 들어, 다음 문은 이름이 ``my-iceberg-tables``인 버킷에 대한 쓰기 액세스를 허용하는 암호화를 사용하여 S3에 대한 외부 볼륨을 생성합니다.

CREATE OR REPLACE EXTERNAL VOLUME my_external_volume
  STORAGE_LOCATIONS =
    (
      (
        NAME = 'my-s3-us-west-2'
        STORAGE_PROVIDER = 'S3'
        STORAGE_BASE_URL = 's3://my-iceberg-tables/'
        STORAGE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/my-write-access-role'
        ENCRYPTION = ( TYPE = 'AWS_SSE_S3' )
      )
    )
  ALLOW_WRITES = TRUE;

전체 지침은 다음 항목을 참조합니다.

• Amazon S3의 외부 볼륨 구성하기

• Google Cloud Storage용 외부 볼륨 구성하기

• Azure Storage용 외부 볼륨 구성하기

필수 권한에 대한 자세한 내용은 저장소에 Snowflake 액세스 권한 부여하기 섹션을 참조하세요.

카탈로그 통합 구성하기¶

외부 관리형 Iceberg 테이블에 작성하려면 Snowflake를 원격 카탈로그에 연결하도록 카탈로그 통합을 구성해야 합니다.

원격 카탈로그는 Open Catalog 또는 `AWS Glue Iceberg REST 카탈로그<https://docs.aws.amazon.com/glue/latest/dg/connect-glu-iceberg-rest.html>`_와 같은 오픈 소스 `Apache Iceberg REST OpenAPI 사양<https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml>`_을 준수해야 합니다.

카탈로그 통합을 생성하려면 다음 항목의 지침을 참조합니다.

• AWS Glue Iceberg REST 에 대한 카탈로그 통합 구성하기. :ref:`읽기 및 쓰기 예제 IAM 정책<label-aws_glue_read_write_permissions>`의 권한을 사용합니다.

  참고

  현재 :doc:`AWS Glue</user-guide/tables-iceberg-configure-catalog-integration-glue>`에 대한 카탈로그 통합을 사용하는 경우 AWS Glue Iceberg REST 엔드포인트에 대한 새 REST 카탈로그 통합을 만들어야 합니다.

• Snowflake Open Catalog 의 카탈로그 통합 구성하기

• Apache Iceberg™ REST 카탈로그에 대한 카탈로그 통합 구성

카탈로그 연결 데이터베이스 만들기¶

Snowflake는 외부 Iceberg REST 카탈로그와 동기화하는 Snowflake 데이터베이스인 카탈로그 연결 데이터베이스에서 쓰기 가능한 외부 관리형 테이블 생성을 지원합니다. Snowflake가 원격 카탈로그에서 자동으로 검색하는 Iceberg 테이블에 작성할 수도 있습니다. 자세한 내용은 Apache Iceberg™ 테이블에 카탈로그 연결 데이터베이스 사용 섹션을 참조하십시오.

다음 예제에서는 CREATE DATABASE(카탈로그 연결) 명령을 사용하여 외부 볼륨을 사용하는 카탈로그 연결 데이터베이스를 생성합니다.

CREATE DATABASE my_catalog_linked_db
  LINKED_CATALOG = (
    CATALOG = 'glue_rest_catalog_int'
  ),
  EXTERNAL_VOLUME = 'my_external_vol';

CREATE SCHEMA 'my_namespace';

DROP SCHEMA 'my_namespace';

Iceberg 테이블 만들기¶

Snowflake에서 작성할 수 있는 외부 관리형 Iceberg 테이블을 만드는 방법은 사용하는 데이터베이스의 종류에 따라 다릅니다.

• 카탈로그 연결 데이터베이스를 사용하는 경우 label-tables_iceberg_external_write_create_table_syntax`를 사용하여 테이블을 생성*하고* 원격 카탈로그에 등록할 수 있습니다. 자세한 지침은 :ref:`label-tables_iceberg_external_writes_create_table_cld 섹션을 참조하십시오.

• (카탈로그에 연결되지 않은) 표준 Snowflake 데이터베이스를 사용하는 경우 먼저 원격 카탈로그에 테이블을 생성해야 합니다. 그런 다음 CREATE ICEBERG TABLE(Iceberg REST 카탈로그) 구문을 사용하여 Snowflake에서 Iceberg 테이블을 만들고 테이블에 작성할 수 있습니다. 자세한 지침은 표준 Snowflake 데이터베이스에서 Iceberg 테이블 만들기 섹션을 참조하십시오.

USE DATABASE my_catalog_linked_db;

USE SCHEMA my_namespace;

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table (
  first_name string,
  last_name string,
  amount int,
  create_date date
)
TARGET_FILE_SIZE = '64MB';

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'my_rest_catalog_integration'
  CATALOG_TABLE_NAME = 'my_remote_table_name';

Iceberg 테이블 삭제하기¶

DROP ICEBERG TABLE 명령을 사용하여 Snowflake 및 원격 카탈로그에서 작성 가능한 외부 관리형 Iceberg 테이블을 동시에 삭제할 수 있습니다.

DROP ICEBERG TABLE my_iceberg_table;

Snowflake는 테이블을 삭제하고 원격 Iceberg 카탈로그를 호출하여 테이블을 삭제하고 테이블의 기본 데이터와 메타데이터를 삭제하도록 지시합니다.

Snowflake는 원격 카탈로그에서 테이블이 삭제되었음을 확인한 경우에만 테이블을 삭제합니다.

외부 관리형 Iceberg 테이블에 쓰기¶

외부 관리형 Iceberg 테이블에 다음 DML 명령을 사용할 수 있습니다.

• INSERT

  • :ref:`예: 쿼리(INSERT INTO … SELECT FROM)<label-insert_multi_row_query_example>`를 사용한 단일 행 삽입

  • 예: INSERT INTO … SELECT FROM(스트림)

• UPDATE

• DELETE

• MERGE

• TRUNCATE TABLE

• COPY INTO <테이블>. 자세한 내용은 Apache Iceberg™ 테이블에 데이터 로드하기 섹션을 참조하십시오.

:doc:`/developer-guide/snowpark/index`를 사용하여 Iceberg 테이블을 처리할 수도 있습니다.

INSERT INTO my_iceberg_table VALUES (1, 'a');
INSERT INTO my_iceberg_table VALUES (2, 'b');
INSERT INTO my_iceberg_table VALUES (3, 'c');

UPDATE my_iceberg_table
  SET a = 10
  WHERE b = 'b';

DELETE my_iceberg_table
  WHERE b = 'a';

MERGE INTO my_iceberg_table USING my_snowflake_table
  ON my_iceberg_table.a = my_snowflake_table.a
  WHEN MATCHED THEN
      UPDATE SET my_iceberg_table.b = my_snowflake_table.b
  WHEN NOT MATCHED THEN
      INSERT VALUES (my_snowflake_table.a, my_snowflake_table.b);

COPY INTO customer_iceberg_ingest
  FROM @my_parquet_stage
  FILE_FORMAT = 'my_parquet_format'
  LOAD_MODE = ADD_FILES_COPY
  PURGE = TRUE
  MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;

CREATE OR REPLACE STREAM my_stream ON TABLE my_snowflake_table;

//...

INSERT INTO my_iceberg_table(id,name)
  SELECT id, name
  FROM my_stream;

def copy_into_iceberg():

  try:
      df = session.table("my_snowflake_table")

      df.write.save_as_table("my_iceberg_table")

  except Exception as e:
      print(f"Error processing {table_name}: {e}")

문제 해결하기¶

Snowflake가 외부 카탈로그에 테이블 변경 사항을 커밋하려고 할 때 문제가 발생하는 경우 Snowflake는 다음 오류 메시지 중 하나를 반환합니다.

004185=SQL Execution Error: Failed while committing transaction to external catalog. Error:''{0}''

004185=SQL Execution Error: Failed while committing transaction to external catalog with unresolvable commit conflicts. Error:''{0}''

004500=SQL Execution Error: Cannot verify the status of transaction from external catalog. The statement ''{0}'' with transaction id {1} may or may not have committed to external catalog. Error:''{2}''