> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ALTER에 대한 문서

# ALTER

대부분의 `ALTER TABLE` 쿼리는 테이블 설정이나 데이터를 수정합니다:

| 수정자                                                                     |
| ----------------------------------------------------------------------- |
| [COLUMN](/ko/reference/statements/alter/column)                         |
| [PARTITION](/ko/reference/statements/alter/partition)                   |
| [DELETE](/ko/reference/statements/alter/delete)                         |
| [UPDATE](/ko/reference/statements/alter/update)                         |
| [ORDER BY](/ko/reference/statements/alter/order-by)                     |
| [SAMPLE BY](/ko/reference/statements/alter/sample-by)                   |
| [INDEX](/ko/reference/statements/alter/skipping-index)                  |
| [PROJECTION](/ko/reference/statements/alter/projection)                 |
| [CONSTRAINT](/ko/reference/statements/alter/constraint)                 |
| [TTL](/ko/reference/statements/alter/ttl)                               |
| [STATISTICS](/ko/reference/statements/alter/statistics)                 |
| [SETTING](/ko/reference/statements/alter/setting)                       |
| [APPLY DELETED MASK](/ko/reference/statements/alter/apply-deleted-mask) |
| [APPLY PATCHES](/ko/reference/statements/alter/apply-patches)           |

<Note>
  대부분의 `ALTER TABLE` 쿼리는 [\*MergeTree](/ko/reference/engines/table-engines/mergetree-family/index), [Merge](/ko/reference/engines/table-engines/special/merge), [Distributed](/ko/reference/engines/table-engines/special/distributed) 테이블에서만 지원됩니다.
</Note>

다음 `ALTER` SQL 문은 뷰를 수정합니다:

| SQL 문                                                               | 설명                                                                            |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| [ALTER TABLE ... MODIFY QUERY](/ko/reference/statements/alter/view) | [구체화된 뷰(Materialized View)](/ko/reference/statements/create/view)의 구조를 수정합니다. |

다음 `ALTER` SQL 문은 역할 기반 접근 제어와 관련된 엔터티를 수정합니다:

| SQL 문                                                               |
| ------------------------------------------------------------------- |
| [USER](/ko/reference/statements/alter/user)                         |
| [ROLE](/ko/reference/statements/alter/role)                         |
| [QUOTA](/ko/reference/statements/alter/quota)                       |
| [ROW POLICY](/ko/reference/statements/alter/row-policy)             |
| [MASKING POLICY](/ko/reference/statements/alter/masking-policy)     |
| [SETTINGS PROFILE](/ko/reference/statements/alter/settings-profile) |

| SQL 문                                                                                | 설명                                                                                         |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| [ALTER TABLE ... MODIFY COMMENT](/ko/reference/statements/alter/comment)             | 이전 설정 여부와 관계없이 테이블 주석을 추가, 수정 또는 제거합니다.                                                    |
| [ALTER DATABASE ... MODIFY COMMENT](/ko/reference/statements/alter/database-comment) | 이전 설정 여부와 관계없이 데이터베이스 주석을 추가, 수정 또는 제거합니다.                                                 |
| [ALTER NAMED COLLECTION](/ko/reference/statements/alter/named-collection)            | [이름이 지정된 컬렉션](/ko/concepts/features/configuration/server-config/named-collections)을 수정합니다. |

<div id="mutations">
  ## 뮤테이션
</div>

테이블 데이터를 변경하기 위한 `ALTER` 쿼리는 "뮤테이션"이라는 메커니즘으로 구현되며, 대표적인 예로 [ALTER TABLE ... DELETE](/ko/reference/statements/alter/delete) 및 [ALTER TABLE ... UPDATE](/ko/reference/statements/alter/update)가 있습니다. 이는 [MergeTree](/ko/reference/engines/table-engines/mergetree-family/index) 테이블의 머지와 유사한 비동기 백그라운드 프로세스로, 파트의 새로운 "뮤테이션된" 버전을 생성합니다.

`*MergeTree` 테이블에서 뮤테이션은 **전체 데이터 파트를 다시 써서** 실행됩니다.
원자성은 보장되지 않습니다. 준비가 완료되는 즉시 기존 파트가 뮤테이션된 파트로 대체되므로, 뮤테이션 도중 실행을 시작한 `SELECT` 쿼리에서는 이미 뮤테이션된 파트의 데이터와 아직 뮤테이션되지 않은 파트의 데이터를 함께 보게 됩니다.

뮤테이션은 생성 순서에 따라 완전히 정렬되며, 각 파트에 그 순서대로 적용됩니다. 또한 뮤테이션은 `INSERT INTO` 쿼리와 부분적인 순서 관계를 가집니다. 즉, 뮤테이션이 제출되기 전에 테이블에 삽입된 데이터는 뮤테이션되지만, 그 이후에 삽입된 데이터는 뮤테이션되지 않습니다. 참고로 뮤테이션은 어떤 방식으로도 삽입을 차단하지 않습니다.

뮤테이션 쿼리는 뮤테이션 항목이 추가된 직후 즉시 반환됩니다(복제된 테이블의 경우 ZooKeeper에, 복제되지 않은 테이블의 경우 파일 시스템에 추가됩니다). 뮤테이션 자체는 시스템 프로필 설정을 사용해 비동기적으로 실행됩니다. 뮤테이션의 진행 상황은 [`system.mutations`](/ko/reference/system-tables/mutations) 테이블을 사용해 추적할 수 있습니다. 성공적으로 제출된 뮤테이션은 ClickHouse 서버가 재시작되더라도 계속 실행됩니다. 제출된 뮤테이션은 롤백할 수 없지만, 어떤 이유로 뮤테이션이 멈춘 경우 [`KILL MUTATION`](/ko/reference/statements/kill#kill-mutation) 쿼리로 취소할 수 있습니다.

완료된 뮤테이션 항목은 즉시 삭제되지 않습니다(보존되는 항목 수는 `finished_mutations_to_keep` 스토리지 엔진 매개변수로 결정됩니다). 오래된 뮤테이션 항목은 삭제됩니다.

<div id="synchronicity-of-alter-queries">
  ## ALTER 쿼리의 동기성
</div>

복제되지 않은 테이블에서는 모든 `ALTER` 쿼리가 동기식으로 수행됩니다. 복제된 테이블에서는 쿼리가 적절한 작업에 대한 지시만 `ZooKeeper`에 추가하고, 실제 작업은 가능한 한 빨리 수행됩니다. 다만, 쿼리는 이러한 작업이 모든 레플리카에서 완료될 때까지 기다릴 수 있습니다.

뮤테이션을 생성하는 `ALTER` 쿼리(예: `UPDATE`, `DELETE`, `MATERIALIZE INDEX`, `MATERIALIZE PROJECTION`, `MATERIALIZE COLUMN`, `APPLY DELETED MASK`, `APPLY PATCHES`, `CLEAR STATISTIC`, `MATERIALIZE STATISTIC` 등이 있으나 이에 국한되지는 않음)의 동기성은 [mutations\_sync](/ko/reference/settings/session-settings/mutations#mutations_sync) 설정으로 정의됩니다.

메타데이터만 수정하는 다른 `ALTER` 쿼리의 경우 [alter\_sync](/ko/reference/settings/session-settings/alter#alter_sync) 설정을 사용해 대기 동작을 설정할 수 있습니다.

비활성 레플리카가 모든 `ALTER` 쿼리를 실행할 때까지 얼마나 오래 기다릴지(초 단위)는 [replication\_wait\_for\_inactive\_replica\_timeout](/ko/reference/settings/session-settings/other#replication_wait_for_inactive_replica_timeout) 설정으로 지정할 수 있습니다.

<Note>
  모든 `ALTER` 쿼리에서 `alter_sync = 2`이고 일부 레플리카가 `replication_wait_for_inactive_replica_timeout` 설정에 지정된 시간보다 오래 비활성 상태로 남아 있으면 `UNFINISHED` 예외가 발생합니다.
</Note>

<div id="concurrent-alter-assignment-on-one-table">
  ### 하나의 테이블에서 동시 `ALTER` 할당
</div>

복제된 테이블에서 동일한 테이블에 여러 개의 개별 `ALTER` 문을 짧은 간격으로 연속 제출하면 `CANNOT_ASSIGN_ALTER`(코드 517) 오류가 발생할 수 있습니다. 레플리카가 이전 `ALTER` 중 일부를 아직 적용하지 않은 경우(메타데이터 버전이 공통 메타데이터보다 뒤처진 경우) 복제 경로에서 이 오류가 발생합니다. 서버는 레플리카가 "still not applied some of previous alters" 또는 "Probably too many alters executing concurrently" 상태라고 표시할 수 있습니다. 이전 `ALTER`가 이미 할당된 후에도 이 상태가 계속될 수 있습니다. 이는 **일반적인 동시 메타데이터 `ALTER` / 뮤테이션** 관련 상태이며, 뮤테이션 전용 SQL 문에만 국한되지 않습니다. 일반적인 동시 메타데이터 변경(`ADD` / `DROP` / `MODIFY` 등)에서도 동일한 재시도 가능한 코드가 발생할 수 있습니다(예를 들어 `tests/queries/0_stateless/03518_alter_logical_race.sh`에서 다루는 재시도 경로를 참조하십시오).

경합을 방지하는 방법:

* 문법에서 허용하는 경우 독립적인 메타데이터 작업을 **하나의** 다중 절 `ALTER`로 결합하십시오(예: 여러 `ADD INDEX` 절).
* `ALTER` 문을 순차적으로 실행하고, 이전 `ALTER`가 레플리카에 적용될 때까지 코드 517 오류 발생 시 재시도하십시오.
* 뮤테이션을 생성하는 `ALTER`의 경우, 다음 작업을 제출하기 전에 [`mutations_sync`](/ko/reference/settings/session-settings/mutations#mutations_sync) 또는 [`system.mutations`](/ko/reference/system-tables/mutations)의 `is_done`과 같은 문서화된 확인 수단을 사용하여 이전 뮤테이션이 완료될 때까지 기다리십시오.

<div id="combining-materialize-index-clauses">
  ### `MATERIALIZE INDEX` 절 함께 사용하기
</div>

하나의 `ALTER`에 여러 `MATERIALIZE INDEX` 절을 포함할 수 있습니다. 현재 트리에서 다루는 사례는 여러 `ADD INDEX` 절과 해당 새 인덱스에 대한 `MATERIALIZE INDEX`를 하나의 SQL 문에 함께 지정하는 것입니다(`tests/queries/0_stateless/02911_add_index_and_materialize_index.sql` 참고). 이렇게 `ADD INDEX`와 `MATERIALIZE INDEX`를 함께 사용하는 형식은 `AlterCommand` 세그먼트와 `MutationCommand` 세그먼트를 혼합하므로, **`DatabaseReplicated`는 이를 `QUERY_IS_PROHIBITED`와 함께 거부합니다**(`InterpreterAlterQuery::validateReplicatedDatabaseSegments`). 일반(`DatabaseReplicated`가 아닌) 데이터베이스에서는 `02911` 예시가 유효합니다. `DatabaseReplicated`에서는 메타데이터 변경과 구체화 뮤테이션을 별도 SQL 문으로 실행하십시오.

현재 구현에서는 뮤테이션을 준비할 때 각 `MATERIALIZE INDEX` 절을 테이블 메타데이터 스냅샷을 기준으로 해석합니다. 따라서 이미 존재하는 인덱스에 대해 구체화만 수행하는 여러 절 형식도 동일한 준비 경로를 따릅니다(뮤테이션만 포함하므로 하나의 세그먼트에 유지됩니다). 이 정확한 형식은 아직 별도의 stateless 테스트로 검증되지 않았습니다. 이러한 테스트가 추가되기 전까지는 별도로 보장되는 계약이 아니라 현재 구현 동작으로 간주하십시오.

순서대로 뮤테이션을 적용해야 한다면, SQL 문마다 `MATERIALIZE INDEX`를 하나씩 실행하고 [`mutations_sync`](/ko/reference/settings/session-settings/mutations#mutations_sync)로 완료를 기다릴 수 있습니다.

<div id="related-content">
  ## 관련 콘텐츠
</div>

* 블로그: [ClickHouse에서 업데이트 및 삭제 처리](https://clickhouse.com/blog/handling-updates-and-deletes-in-clickhouse)