아이스버그 테이블 변경

아이스버그 테이블 변경 (ALTER ICEBERG TABLE)

ALTER ICEBERG TABLE

기존 Apache Iceberg™ table의 클러스터링 옵션 및 태그와 같은 속성을 수정합니다.

표준 Snowflake 데이터베이스에 있는 외부 관리 Iceberg 테이블의 카탈로그 통합을 다른 카탈로그 통합으로 교체하려면 SYSTEM$SET_CATALOG_INTEGRATION을 참조하세요.

또한 ALTER ICEBERG TABLE 문을 사용하여 테이블을 새로 고치거나, 테이블을 변환하거나, 구조적 타입 열을 변경하거나, 파티션 사양을 변경(evolve)할 수 있습니다. 이러한 작업의 구문은 상당히 다릅니다. 이러한 작업에 대한 구문, 매개변수 설명, 사용 참고 사항 및 예제를 보려면 다음 페이지를 참조하세요.

이 항목에서는 혼동을 피하기 위해 Iceberg tables라고 명시해야 하는 경우를 제외하고 Iceberg 테이블을 단순히 "tables"로 지칭합니다.

참조:

CREATE ICEBERG TABLE , DROP ICEBERG TABLE , SHOW ICEBERG TABLES , DESCRIBE ICEBERG TABLE

출처: 문서

본문

구문

ALTER ICEBERG TABLE [ IF EXISTS ]  { clusteringAction | tableColumnAction }

ALTER ICEBERG TABLE [ IF EXISTS ]  SET
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ CATALOG_SYNC = '']
  [ DATA_RETENTION_TIME_IN_DAYS =  ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ TARGET_FILE_SIZE = { AUTO | 16MB | 32MB | 64MB | 128MB } ]
  [ PATH_LAYOUT = { FLAT | HIERARCHICAL } ]
  [ CONTACT (  =  [ ,  =  ... ] ) ]
  [ LOG_EVENT_LEVEL = { ERROR | WARN | DEBUG } ]
  [ ERROR_LOGGING = { TRUE | FALSE } ]
  [ ENABLE_DATA_COMPACTION = { TRUE | FALSE } ]
  [ ICEBERG_MERGE_ON_READ_BEHAVIOR = { 'AUTO' | 'ENABLED' | 'DISABLED' } ]
  [ ENABLE_ICEBERG_MERGE_ON_READ = { TRUE | FALSE } ]

ALTER ICEBERG TABLE [ IF EXISTS ]  UNSET
  [ REPLACE_INVALID_CHARACTERS ]
  [ LOG_EVENT_LEVEL ]
  [ ERROR_LOGGING ]
  [ ENABLE_DATA_COMPACTION ]
  [ ICEBERG_MERGE_ON_READ_BEHAVIOR ]
  [ ENABLE_ICEBERG_MERGE_ON_READ ]

ALTER ICEBERG TABLE [ IF EXISTS ] dataGovnPolicyTagAction

ALTER ICEBERG TABLE [ IF EXISTS ]  searchOptimizationAction

여기서:

clusteringAction ::=
  {
     CLUSTER BY (  [ ,  , ... ] )
     /* { SUSPEND | RESUME } RECLUSTER is valid action */
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }

tableColumnAction ::=
  {
     ADD [ COLUMN ] [ IF NOT EXISTS ]   [ DEFAULT  ]
        [ inlineConstraint ]
        [ COLLATE '' ]

   | RENAME COLUMN  TO 

   | ALTER | MODIFY [ ( ]
                          , [ COLUMN ]  { [ SET ] NOT NULL | DROP NOT NULL }
                          , [ COLUMN ]  [ [ SET DATA ] TYPE ] 
                          , [ COLUMN ]  COMMENT ''
                          , [ COLUMN ]  UNSET COMMENT
                          , [ COLUMN ]  SET WRITE DEFAULT 
                          , [ COLUMN ]  DROP WRITE DEFAULT
                        [ , [ COLUMN ]  ... ]
                        [ , ... ]
                    [ ) ]

   | DROP [ COLUMN ] [ IF EXISTS ]  [,  ... ]
  }

  inlineConstraint ::=
    [ NOT NULL ]
    [ CONSTRAINT  ]
    {
        UNIQUE
      | PRIMARY KEY
      | [ FOREIGN KEY ] REFERENCES  [ (  ) ]
      | CHECK (  )
    }
    [  ]

dataGovnPolicyTagAction ::=
  {
      SET TAG  = '' [ ,  = '' ... ]
    | UNSET TAG  [ ,  ... ]
  }
  |
  {
      ADD ROW ACCESS POLICY  ON (  [ , ... ] )
    | DROP ROW ACCESS POLICY 
    | DROP ROW ACCESS POLICY  ,
        ADD ROW ACCESS POLICY  ON (  [ , ... ] )
    | DROP ALL ROW ACCESS POLICIES
  }
  |
  {
      SET AGGREGATION POLICY 
        [ ENTITY KEY (  [, ... ] ) ]
        [ FORCE ]
    | UNSET AGGREGATION POLICY
  }
  |
  {
      SET JOIN POLICY 
        [ FORCE ]
    | UNSET JOIN POLICY
  }
  |
  ADD [ COLUMN ] [ IF NOT EXISTS ]  
    [ [ WITH ] MASKING POLICY 
          [ USING (  ,  , ... ) ] ]
    [ [ WITH ] PROJECTION POLICY  ]
    [ [ WITH ] TAG (  = ''
          [ ,  = '' , ... ] ) ]
  |
  {
    { ALTER | MODIFY } [ COLUMN ] 
        SET MASKING POLICY 
          [ USING (  ,  , ... ) ] [ FORCE ]
      | UNSET MASKING POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] 
        SET PROJECTION POLICY 
          [ FORCE ]
      | UNSET PROJECTION POLICY
  }
  |
  { ALTER | MODIFY } [ COLUMN ]  SET TAG
       = '' [ ,  = '' ... ]
      , [ COLUMN ]  SET TAG
           = '' [ ,  = '' ... ]
  |
  { ALTER | MODIFY } [ COLUMN ]  UNSET TAG  [ ,  ... ]
                   , [ COLUMN ]  UNSET TAG  [ ,  ... ]

searchOptimizationAction ::=
  {
     ADD SEARCH OPTIMIZATION [
       ON  [ ,  ... ]
     ]

   | DROP SEARCH OPTIMIZATION [
       ON {  |  |  }
          [ , ... ]
     ]
  }

자세한 내용은 를 참조하세요.

매개변수

table_name

수정할 테이블의 식별자입니다.

식별자에 공백이나 특수 문자가 포함된 경우 전체 문자열을 큰따옴표로 묶어야 합니다. 큰따옴표로 묶인 식별자는 대소문자를 구분합니다.

자세한 내용은 Identifier requirements를 참조하세요.

SET ...

외부 테이블에 설정할 하나 이상의 속성/매개변수를 지정합니다(공백, 쉼표 또는 줄바꿈으로 구분).

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

쿼리 결과에서 잘못된 UTF-8 문자를 유니코드 대체 문자(�)로 바꿀지 여부를 지정합니다. 이 매개변수는 외부 Iceberg 카탈로그를 사용하는 테이블에서만 설정할 수 있습니다.

  • TRUE는 잘못된 UTF-8 문자를 유니코드 대체 문자로 바꿉니다.
  • FALSE는 잘못된 UTF-8 문자를 그대로 둡니다. Snowflake는 Parquet 데이터 파일에서 잘못된 UTF-8 문자를 발견하면 사용자 오류 메시지를 반환합니다.

지정하지 않으면 Iceberg 테이블은 스키마, 데이터베이스 또는 계정의 매개변수 값을 기본값으로 사용합니다. 스키마는 데이터베이스보다 우선하고, 데이터베이스는 계정보다 우선합니다.

기본값: FALSE

CATALOG_SYNC = 'snowflake_open_catalog_integration_name'

Snowflake Open Catalog에 대해 구성된 카탈로그 통합의 이름을 지정합니다. Snowflake는 테이블을 %snowflakeopencatalog% 계정의 외부 카탈로그와 동기화합니다. Snowflake 관리 Iceberg 테이블을 Open Catalog와 동기화하는 방법에 대한 자세한 내용은 Sync a Snowflake-managed table with Snowflake Open Catalog를 참조하세요.

이 매개변수에 대한 자세한 내용은 를 참조하세요.

DATA_RETENTION_TIME_IN_DAYS = integer

Snowflake 관리 테이블의 보존 기간을 지정해서 테이블의 과거 데이터에 대해 Time Travel 작업(SELECT, CLONE, UNDROP)을 수행할 수 있게 해요. 자세한 내용은 Understanding & using Time Travel을(를) 참조하세요.

이 객체 수준 파라미터에 대한 자세한 설명과 객체 파라미터에 대한 추가 정보는 Parameters을(를) 참조하세요.

값:

  • Standard Edition: 0 또는 1
  • Enterprise Edition: 영구 테이블의 경우 0~90

기본값:

  • Standard Edition: 1
  • Enterprise Edition(이상): 1 (스키마, 데이터베이스 또는 계정 수준에서 다른 기본값을 지정하지 않은 경우)

0 값은 테이블에 대해 Time Travel을 사실상 비활성화해요.

AUTO_REFRESH = { TRUE | FALSE }

Snowflake가 테이블과 연결된 외부 Iceberg 카탈로그를 자동으로 폴링해서 메타데이터 업데이트를 확인할지 여부를 지정해요.

카탈로그 통합에서 REFRESH_INTERVAL_SECONDS 파라미터에 값을 지정하지 않으면 Snowflake는 기본 새로 고침 간격인 30초를 사용해요.

자세한 내용은 automated refresh을(를) 참조하세요.

기본값: FALSE

AUTO_REFRESH를 INFER_SCHEMA와 함께 사용하는 것은 지원되지 않아요.

TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }'

테이블의 대상 Parquet 파일 크기를 지정해요.

  • '{ 16MB | 32MB | 64MB | 128MB }'은(는) 테이블의 고정 대상 파일 크기를 지정해요.
  • 'AUTO'는 테이블 유형에 따라 다르게 작동해요:
    • Snowflake 관리 테이블: AUTO는 Snowflake가 테이블 크기, DML 패턴, 수집 워크로드, 클러스터링 구성 같은 테이블 특성에 따라 파일 크기를 선택하도록 지정해요. Snowflake는 16MB부터 시작해서 Snowflake에서 읽기 및 쓰기 성능을 높이기 위해 파일 크기를 자동으로 조정해요. 이 옵션을 사용해서 Snowflake에서 테이블 성능을 최적화하세요.
    • 외부 관리 테이블: AUTO는 Snowflake가 최대 파일 크기(128MB)까지 적극적으로 확장하도록 지정해요.

자세한 내용은 을(를) 참조하세요.

기본값: AUTO

PATH_LAYOUT = { FLAT | HIERARCHICAL }

Specifies the path layout that Snowflake uses when writing Parquet data files to the table. You can set this parameter for an existing table.

이 매개 변수는 Snowflake가 테이블에 Parquet 데이터 파일을 쓸 때 사용하는 경로 레이아웃을 지정해요. 기존 테이블에 대해 이 매개 변수를 설정할 수 있어요.

For more information about this parameter, see .

이 매개 변수에 대한 자세한 내용은 을(를) 참조해요.

CONTACT purpose = contact [ , purpose = contact ... ]

Associate the existing object with one or more contacts. For a list of valid purposes, see .

기존 객체를 하나 이상의 contacts와 연결해요. 유효한 용도 목록은 을(를) 참조해요.

You cannot set the CONTACT property with other properties in the same statement.

같은 문에서 CONTACT 속성을 다른 속성과 함께 설정할 수 없어요.

LOG_EVENT_LEVEL = { ERROR | WARN | DEBUG }

Specifies the severity level of automated refresh log events that should be ingested and made available in the active event table. The LOG_EVENT_LEVEL parameter determines which events to capture based on the following values:

자동 새로 고침 로그 이벤트 중 활성 이벤트 테이블에 수집되어 제공되어야 하는 심각도 수준을 지정해요. LOG_EVENT_LEVEL 매개 변수는 다음 값에 따라 캡처할 이벤트를 결정해요:

  • ERROR: Events that signal a change requiring human intervention to resolve.

  • WARN: Events that signal an issue that can be resolved without human intervention.

  • DEBUG: High-volume events.

  • ERROR: 해결을 위해 사람의 개입이 필요한 변경을 알리는 이벤트예요.

  • WARN: 사람의 개입 없이 해결할 수 있는 문제를 알리는 이벤트예요.

  • DEBUG: 대용량 이벤트예요.

There is no default severity level. To capture events, you must set the severity level at either the Iceberg table level or account level.

기본 심각도 수준은 없어요. 이벤트를 캡처하려면 Iceberg 테이블 수준이나 계정 수준에서 심각도 수준을 설정해야 해요.

For more information, see .

자세한 내용은 을(를) 참조해요.

ERROR_LOGGING = { TRUE | FALSE }

Specifies whether to turn on DML error logging for the table.

테이블에 대해 DML 오류 로깅을 켤지 여부를 지정해요.

  • TRUE turns on DML error logging for the table.

  • FALSE turns off DML error logging for the table.

  • TRUE는 테이블에 대해 DML 오류 로깅을 켜요.

  • FALSE는 테이블에 대해 DML 오류 로깅을 꺼요.

For more information, see .

자세한 내용은 을(를) 참조해요.

If the parameter is set to TRUE for a session, DML error logging isn't turned on, regardless of whether it is turned on for specific tables.

세션에 대해 매개 변수가 TRUE로 설정된 경우, 특정 테이블에 대해 켜져 있는지와 관계없이 DML 오류 로깅이 켜지지 않아요.

ENABLE_DATA_COMPACTION = { TRUE | FALSE }

Specifies whether Snowflake should enable data compaction on the table. You can only set this parameter for Snowflake-managed tables.

Snowflake가 테이블에서 데이터 컴팩션을 활성화할지 여부를 지정해요. 이 매개 변수는 Snowflake 관리 테이블에 대해서만 설정할 수 있어요.

  • TRUE: Snowflake performs data compaction on the table.

  • FALSE: Snowflake doesn't perform data compaction on the table.

  • TRUE: Snowflake가 테이블에서 데이터 컴팩션을 수행해요.

  • FALSE: Snowflake가 테이블에서 데이터 컴팩션을 수행하지 않아요.

Default: TRUE

기본값: TRUE

For more information, see and .

자세한 내용은 및 을(를) 참조해요.

ICEBERG_MERGE_ON_READ_BEHAVIOR = { 'AUTO' | 'ENABLED' | 'DISABLED' }

이 %iceberg-tm% 테이블에서 Snowflake가 행 수준 업데이트(UPDATE, DELETE, MERGE)를 수행하는 방식을 지정해요. merge-on-read(데이터와 함께 Iceberg 삭제 파일을 작성하는 방식)와 copy-on-write(전체 데이터 파일을 다시 작성하는 방식) 중에서 선택해요.

이 파라미터를 설정하지 않으면 Iceberg 테이블은 스키마, 데이터베이스 또는 계정의 설정을 상속해요. 스키마가 데이터베이스보다 우선하고, 데이터베이스가 계정보다 우선해요.

파라미터 값은 대소문자를 구분하지 않아요.

값:

'AUTO': Snowflake가 테이블의 Iceberg 형식 버전과 관리 모드에 따라 merge-on-read 또는 copy-on-write를 선택해요. 자세한 내용은 을(를) 참조해요.

'ENABLED': 테이블이 merge-on-read를 사용해요. %iceberg-tm% 테이블 사양 v2를 준수하는 테이블의 경우 Snowflake는 행 수준 삭제를 위해 위치 기반 삭제 파일을 작성해요. v3를 준수하는 테이블의 경우 조건이 충족되면 Snowflake는 삭제 벡터를 작성해요.

'DISABLED': 테이블은 모든 DML 작업에 copy-on-write를 사용해요.

기본값:

'AUTO'

이 파라미터에 대한 자세한 설명은 을(를) 참조해요.

ENABLE_ICEBERG_MERGE_ON_READ = { TRUE | FALSE }

이 파라미터는 더 이상 사용되지 않아요(비권장). 대신 ICEBERG_MERGE_ON_READ_BEHAVIOR을(를) 사용하세요. 레거시 파라미터는 ICEBERG_MERGE_ON_READ_BEHAVIOR가 기본값('AUTO')일 때 여전히 적용되지만, 향후 릴리스에서는 오류를 반환할 거예요.

테이블이 merge-on-read 동작을 사용할지 여부를 지정해요.

이 파라미터를 설정하지 않으면 Iceberg 테이블은 스키마, 데이터베이스 또는 계정에 지정된 merge-on-read 동작을 기본으로 사용해요. 스키마가 데이터베이스보다 우선하고, 데이터베이스가 계정보다 우선해요.

값:

TRUE: 테이블이 merge-on-read 동작을 사용해요. 테이블이 %iceberg-tm% 테이블 사양 v2 또는 v3를 준수하는지 여부에 따라 동작은 다음 목록과 같아요:

  • 테이블이 v2를 준수하면 Snowflake는 행 수준 삭제를 위해 위치 기반 삭제 파일을 사용해요.
  • 테이블이 v3를 준수하면 조건이 충족될 때 Snowflake는 행 수준 삭제를 위해 삭제 벡터를 사용해요.

참고: 이 매개변수를 TRUE로 설정해도 Snowflake 관리 v2 Iceberg 테이블에서 merge-on-read가 활성화되지는 않아요. ICEBERG_MERGE_ON_READ_BEHAVIOR가 기본값('AUTO')인 경우, 이 설정은 자동 매트릭스를 통해 처리되며, Snowflake 관리 v2 테이블은 copy-on-write 방식으로 유지돼요. Snowflake 관리 v2 테이블에서 merge-on-read를 활성화하려면 테이블, 스키마, 데이터베이스 또는 계정에 ICEBERG_MERGE_ON_READ_BEHAVIOR = 'ENABLED'를 설정하세요.

FALSE: 테이블이 copy-on-write 동작을 사용해요.

기본값: TRUE

이 매개변수에 대한 자세한 설명은 를 참조하세요.

UNSET

현재 이 명령으로 다음 매개변수만 설정 해제(unset)할 수 있어요.

  • REPLACE_INVALID_CHARACTERS
  • CATALOG_SYNC
  • LOG_EVENT_LEVEL
  • ENABLE_DATA_COMPACTION
  • ICEBERG_MERGE_ON_READ_BEHAVIOR
  • ENABLE_ICEBERG_MERGE_ON_READ

클러스터링 작업 (clusteringAction)

클러스터링은 Snowflake를 Iceberg 카탈로그로 사용하는 테이블에서만 지원돼요.

CLUSTER BY ( expr [ , expr , ... ] )

테이블의 클러스터링 키로 하나 이상의 테이블 열 또는 열 표현식을 지정(또는 수정)해요. Automatic Clustering이 클러스터링을 유지 관리하는 열/표현식이에요.

클러스터링에 대해 자세히 알아보려면 Clustering Keys & Clustered Tables를 참조하세요.

SUSPEND | RESUME RECLUSTER

테이블에 대해 Automatic Clustering을 활성화하거나 비활성화해요.

DROP CLUSTERING KEY

테이블의 클러스터링 키를 제거해요.

클러스터링 키와 리클러스터링에 대한 자세한 내용은 Understanding Snowflake Table Structures를 참조하세요.

테이블 열 작업 (tableColumnAction)

ADD [ COLUMN ] [ IF NOT EXISTS ] col_name col_data_type [ DEFAULT col_default ] [ inlineConstraint ] [ COLLATE 'collation_specification' ] [ , ... ]

새 열을 추가해요. 기본값, 인라인 제약 조건, collation specification을 지정할 수 있어요.

테이블 열 작업에 대한 추가 세부 정보는 다음을 참조하세요.

같은 명령에서 여러 컬럼에 대해 ADD COLUMN 작업을 수행할 수 있어요.

컬럼이 이미 존재하는지 확실하지 않다면, 컬럼을 추가할 때 IF NOT EXISTS를 지정할 수 있어요. 컬럼이 이미 존재하는 경우, ADD COLUMN은 기존 컬럼에 아무런 영향을 주지 않고 오류를 발생시키지 않아요.

새 컬럼에 대해 다음 중 하나도 함께 지정하는 경우에는 IF NOT EXISTS를 지정할 수 없어요:

  • AUTOINCREMENT 또는 IDENTITY
  • UNIQUE, PRIMARY KEY 또는 FOREIGN KEY

DEFAULT col_default

Iceberg 버전 3(v3) 테이블에서만 컬럼의 기본값을 지정해요. 컬럼의 데이터 타입이 문자열(string)인 경우, 기본값을 작은따옴표로 감싸야 해요.

지정한 값은 컬럼의 초기 기본값(initial default)과 쓰기 기본값(write default)으로 모두 사용돼요. 컬럼의 쓰기 기본값을 변경하려면 ALTER ICEBERG TABLE ... ALTER COLUMN ... SET WRITE DEFAULT를 사용하세요.

컬럼에 기본값을 지정할 때는 정적(static) 값을 지정해야 해요. 값에 표현식(expression)이나 함수(function)를 지정할 수 없어요. 이 요구 사항은 Iceberg v3 사양을 따르며, 초기 기본값과 쓰기 기본값 모두에 적용돼요.

Iceberg 테이블에서 기본값 사용에 대한 자세한 내용은 를 참조하세요.

RENAME COLUMN col_name to new_col_name

지정한 컬럼을 테이블의 다른 컬럼에서 현재 사용되지 않는 새 이름으로 변경해요.

클러스터링 키(clustering key)의 일부인 컬럼은 이름을 변경할 수 없어요.

테이블이나 컬럼 같은 객체의 이름을 변경할 때는 해당 객체를 참조하는 다른 객체도 새 이름으로 업데이트해야 해요.

{ ALTER | MODIFY } COLUMN col_name ...

컬럼의 속성을 수정해요.

SET WRITE DEFAULT col_default

Iceberg 버전 3(v3) 테이블에서만 컬럼의 쓰기 기본값(write default)을 지정해요. 컬럼의 데이터 타입이 문자열(string)인 경우, 기본값을 작은따옴표로 감싸야 해요.

컬럼에 이미 쓰기 기본값이 있는 경우, 이 설정을 사용하여 쓰기 기본값을 변경할 수 있어요.

컬럼에 기본값을 지정할 때는 정적 값을 지정해야 해요. 값에 표현식이나 함수를 지정할 수는 없어요. 이 요구 사항은 Iceberg v3 사양을 따르며, 초기 기본값과 쓰기 기본값 모두에 적용돼요.

Iceberg 테이블에서 기본값을 사용하는 방법에 대한 자세한 내용은 를 참조하세요.

DROP WRITE DEFAULT

Iceberg 버전 3(v3) 테이블에서만 컬럼의 쓰기 기본값을 삭제해요.

Iceberg 테이블에서 기본값을 사용하는 방법에 대한 자세한 내용은 를 참조하세요.

DROP COLUMN [ IF EXISTS ] col_name [ CASCADE | RESTRICT ]

지정한 컬럼을 테이블에서 제거해요.

컬럼이 이미 존재하는지 확실하지 않다면, 컬럼을 삭제할 때 IF EXISTS를 지정할 수 있어요. 컬럼이 존재하지 않으면 DROP COLUMN은 아무 효과도 없고 오류가 발생하지 않아요.

컬럼 삭제는 메타데이터 전용 작업이에요. 마이크로 파티션을 즉시 다시 쓰지 않으므로 컬럼이 사용하던 공간도 즉시 확보되지 않아요. 일반적으로 개별 마이크로 파티션 내부의 공간은 해당 마이크로 파티션이 다음에 다시 쓰일 때 확보되는데, 이는 보통 DML (INSERT, UPDATE, DELETE)이나 리클러스터링(re-clustering)으로 인해 쓰기가 발생할 때예요.

데이터 거버넌스 정책 및 태그 작업 (dataGovnPolicyTagAction)

TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

tag 이름과 태그 문자열 값을 지정해요.

태그 값은 항상 문자열이며, 태그 값의 최대 문자 수는 256자예요.

문에서 태그를 지정하는 방법에 대한 자세한 내용은 를 참조하세요.

policy_name

정책의 식별자이며, 스키마 내에서 고유해야 해요.

다음 절들은 행 액세스 정책(row access policy)을 지원하는 모든 테이블 종류에 적용돼요. 예를 들어 테이블, 뷰, 이벤트 테이블 등이 포함되지만 이에 국한되지 않아요. 설명을 간단히 하기 위해 절에서는 그냥 "테이블"이라고 표현할게요.

ADD ROW ACCESS POLICY policy_name ON (col_name [ , ... ])

테이블에 행 액세스 정책을 추가해요.

최소한 하나의 컬럼 이름을 지정해야 합니다. 추가 컬럼은 각 컬럼 이름을 쉼표로 구분하여 지정할 수 있습니다. 이 표현식을 사용하여 이벤트 테이블과 외부 테이블 모두에 행 액세스 정책을 추가할 수 있습니다.

DROP ROW ACCESS POLICY policy_name

테이블에서 행 액세스 정책을 제거합니다.

이 절을 사용하여 테이블에서 정책을 제거할 수 있습니다.

DROP ROW ACCESS POLICY policy_name, ADD ROW ACCESS POLICY policy_name ON ( col_name [ , ... ] )

테이블에 설정된 행 액세스 정책을 제거하고 동일한 테이블에 행 액세스 정책을 하나의 SQL 문으로 추가합니다.

DROP ALL ROW ACCESS POLICIES

테이블에서 모든 row access policy 연결을 제거합니다.

이 표현식은 스키마에서 행 액세스 정책을 제거한 후 이벤트 테이블에서 정책을 제거할 때 유용합니다. 이 표현식을 사용하여 테이블에서 행 액세스 정책 연결을 제거할 수 있습니다.

백업을 만들 때 테이블에 행 액세스 정책이 적용되어 있었고 나중에 해당 정책이 제거된 경우를 가정해 보세요. backup에서 테이블을 복원한 후에는 DROP ALL ROW ACCESS POLICIES 절이 포함된 ALTER TABLE 명령을 실행할 때까지 테이블을 쿼리할 수 없습니다.

SET AGGREGATION POLICY policy_name

[ ENTITY KEY (col_name [ , ... ]) ] [ FORCE ]

테이블에 aggregation policy를 할당합니다.

선택적 ENTITY KEY 매개변수를 사용하여 테이블 내에서 엔터티를 고유하게 식별하는 컬럼을 정의할 수 있습니다. 자세한 내용은 Implementing entity-level privacy with aggregation policies를 참조하세요.

선택적 FORCE 매개변수를 사용하여 기존 집계 정책을 새 집계 정책으로 원자적으로 교체할 수 있습니다.

UNSET AGGREGATION POLICY

테이블에서 집계 정책을 분리합니다.

SET JOIN POLICY policy_name

[ FORCE ]

테이블에 join policy를 할당합니다.

선택적 FORCE 매개변수를 사용하여 기존 조인 정책을 새 조인 정책으로 원자적으로 교체할 수 있습니다.

UNSET JOIN POLICY

테이블에서 조인 정책을 분리합니다.

{ ALTER | MODIFY } [ COLUMN ] ...

USING ( col_name , cond_col_1 ... )

조건부 마스킹 정책 SQL 표현식에 전달할 인자를 지정해요.

목록의 첫 번째 열은 정책 조건이 데이터를 마스킹하거나 토큰화할 열을 지정하며, 마스킹 정책이 설정된 열과 일치해야 해요.

추가 열은 첫 번째 열에 대해 쿼리가 수행될 때 쿼리 결과의 각 행에서 데이터를 마스킹하거나 토큰화할지 결정하기 위해 평가할 열을 지정해요.

USING 절이 생략되면 Snowflake는 조건부 마스킹 정책을 일반 마스킹 정책으로 취급해요.

FORCE

단일 문에서 열에 현재 설정된 마스킹 또는 프로젝션 정책을 다른 정책으로 교체해요.

참고로 마스킹 정책과 함께 FORCE 키워드를 사용하려면 ALTER TABLE 문의 정책 데이터 타입(예: STRING)이 열에 현재 설정된 마스킹 정책의 데이터 타입(예: STRING)과 일치해야 해요.

열에 마스킹 정책이 현재 설정되어 있지 않으면 이 키워드를 지정해도 효과가 없어요.

자세한 내용은 또는 를 참조해요.

검색 최적화 작업 (searchOptimizationAction)

ADD SEARCH OPTIMIZATION

테이블 전체에 대해 검색 최적화를 추가하거나, 선택적 ON 절을 지정하면 특정 열에 대해 추가해요.

검색 최적화는 특히 테이블의 데이터가 자주 변경되는 경우 유지 비용이 많이 들 수 있어요. 자세한 내용은 를 참조해요.

ON search_method_with_target [, search_method_with_target ... ]

테이블 전체 대신 특정 열에 대해 검색 최적화를 구성하려는 경우에 지정해요.

search_method_with_target에는 다음 구문의 표현식을 사용해요:

(  [ ,  , ... ] [ , ANALYZER => '' ] )

여기서:

  • search_method는 특정 유형의 조건(predicate)에 대한 쿼리를 최적화하는 다음 방법 중 하나를 지정해요:
검색 방법 설명
FULL_TEXT VARCHAR(text) 유형을 사용하는 조건자입니다.
EQUALITY 동등(Equality) 및 IN 조건자입니다.
SUBSTRING substri[[ NOT ] LIKE]s 및 정규식과 일치하는 조건자입니다 (for ex[[ NOT ] ILIKE]ple, [](/sql-reference/functions/l[[ NOT ] RLIKE]e), [REGEXP_LIKE], 및 ).

  • target은 열 또는 별표(*)를 지정합니다.

    search_method 값에 따라 다음 유형 중 하나의 열을 지정할 수 있어요:

    검색 방법 지원되는 대상
    FULL_TEXT VARCHAR(text) 데이터 유형의 열입니다.
    EQUALITY 숫자, 문자열, 이진 데이터 유형의 열입니다.
    SUBSTRING VARCHAR(text) 데이터 유형의 열입니다.

    테이블의 모든 적용 가능한 열을 대상으로 지정하려면 별표(*)를 사용해요.

    특정 검색 방법에 대해 별표와 특정 열 이름을 함께 지정할 수 없다는 점에 유의하세요. 하지만 서로 다른 검색 방법에서는 별표를 지정할 수 있어요.

    예를 들어, 다음 표현식을 지정할 수 있어요:

    -- Allowed
ON SUBSTRING(*)
ON EQUALITY(*), SUBSTRING(*)

    다음 표현식은 지정할 수 없어요:

    -- Not allowed
ON EQUALITY(*, c1)
ON EQUALITY(c1, *)
ON EQUALITY(v1:path, *)
ON EQUALITY(c1), EQUALITY(*)

  • ANALYZER => 'analyzer_name'은 search_method가 FULL_TEXT인 경우 텍스트 분석기의 이름을 지정해요.

    검색 최적화 분석기에 대한 자세한 내용은 ALTER TABLE을 참조해요.

대상에 여러 검색 방법을 지정하려면 쉼표를 사용하여 각 후속 방법과 대상을 구분해요:

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1), EQUALITY(c2, c3);

같은 테이블에 대해 ALTER ICEBERG TABLE ... ADD SEARCH OPTIMIZATION ON ... 명령을 여러 번 실행하면 각 후속 명령이 테이블의 기존 구성에 추가돼요. 예를 들어, 다음 명령을 실행한다고 가정해 보세요:

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2);
ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c3, c4);

이렇게 하면 테이블 구성에 c1, c2, c3, c4 열에 대한 동등 조건이 추가돼요. 이는 다음 명령을 실행하는 것과 동일해요:

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2, c3, c4);

예시는 를 참조하세요.

DROP SEARCH OPTIMIZATION

DROP SEARCH OPTIMIZATION은 테이블 전체에서 search optimization을 제거하거나, 선택적 ON 절을 지정하면 특정 열에서 제거해요.

  • 테이블에 search optimization 속성이 있으면 테이블을 삭제했다가 다시 복원해도 search optimization 속성은 유지돼요.
  • 테이블에서 search optimization 속성을 제거한 후 다시 추가하면 처음 추가할 때와 동일한 비용이 들어요.

ON search_method_with_target | column_name | expression_id [ , ... ]

ON 절은 테이블 전체에서 search optimization을 제거하는 대신 특정 열에 대한 search optimization 구성을 제거하고 싶을 때 지정해요.

제거할 열 구성을 지정하려면 다음 중 하나를 지정해요:

  • search_method_with_target의 경우 하나 이상의 특정 열에 대한 쿼리를 최적화하는 메서드를 지정해요. 앞에서 설명한 구문을 사용하세요.
  • column_name의 경우 search optimization으로 구성된 열의 이름을 지정해요. 열 이름을 지정하면 해당 열의 모든 표현식이 제거돼요.
  • expression_id의 경우 DESCRIBE SEARCH OPTIMIZATION 명령의 출력에 나열된 표현식의 ID를 지정해요.

이 중 두 개 이상을 지정하려면 항목 사이에 쉼표를 사용해요.

검색 메서드(대상 포함), 열 이름, 표현식 ID는 어떤 조합으로도 지정할 수 있어요.

예시는 를 참조하세요.

액세스 제어 요구 사항

이 작업을 실행하는 데 사용되는 role은 최소한 다음 privileges을 보유해야 해요:

권한 객체 참고
OWNERSHIP Iceberg table %ac-ownership%
USAGE External volume
USAGE Catalog integration 테이블이 catalog integration을 사용하는 경우 필요합니다.

schema의 객체에 대해 작업하려면 상위 database에 대한 권한이 하나 이상 필요하고 상위 schema에 대한 권한도 하나 이상 필요합니다.

지정된 권한 집합을 가진 custom role을 만드는 방법은 을(를) 참조하세요.

securable objects에 대해 SQL 작업을 수행하기 위한 role 및 privilege grant에 대한 일반적인 정보는 Overview of Access Control을(를) 참조하세요.

사용 참고 사항

  • 테이블 소유자(즉, 테이블에 대한 OWNERSHIP 권한이 있는 role) 또는 상위 role만 이 명령을 실행할 수 있습니다.

  • 클러스터링은 Snowflake를 Iceberg catalog로 사용하는 테이블에서만 지원됩니다. Iceberg table에 클러스터링을 추가하려면 테이블이 포함된 schema와 database에 대한 USAGE 또는 OWNERSHIP 권한도 있어야 합니다.

  • catalog-linked database의 테이블에서는 다음 기능이 지원되지 않습니다.

    • 기존 column에 NOT NULL, COMMENT, DATA TYPE 속성을 설정하는 것.
    • column 제약 조건을 설정하는 것.
    • 클러스터링.

  • Iceberg table에서 ALTER TABLE 명령을 실행하여 data metric functions를 사용할 수 있습니다. 자세한 내용은 Use SQL to set up data metric functions을(를) 참조하세요.

  • Iceberg table에서 search optimization을 사용하는 방법과 제한 사항을 포함한 자세한 내용은 search optimization 문서의 을(를) 참조하세요.

  • 메타데이터 관련:

  • CATALOG_SYNC parameter 변경 시 문제를 해결하려면 을(를) 참조하세요.

예제

다음 예제는 Iceberg 테이블에 customer 값을 가진 my_tag 태그를 설정합니다.

ALTER ICEBERG TABLE my_iceberg_table SET TAG my_tag = 'customer';

다음 예제는 기존 외부 관리 테이블에 대해 자동 새로 고침을 활성화합니다.

ALTER ICEBERG TABLE my_iceberg_table SET AUTO_REFRESH = TRUE;

다음 예제들은 Iceberg 테이블에 대한 검색 최적화를 추가하고 제거합니다.

ALTER ICEBERG TABLE my_iceberg_table ADD SEARCH OPTIMIZATION ON SUBSTRING(C6);

ALTER ICEBERG TABLE my_iceberg_table DROP SEARCH OPTIMIZATION ON EQUALITY(C7, C8);

더 알아보기 (Learn more)