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

# Postgres ClickPipe의 병렬 스냅샷

> Postgres ClickPipe의 병렬 스냅샷을 설명하는 문서

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

이 문서에서는 Postgres ClickPipe의 병렬 스냅샷/초기 적재 동작 방식과 이를 제어하는 데 사용할 수 있는 스냅샷 매개변수를 설명합니다.

<div id="overview-pg-snapshot">
  ## 개요
</div>

초기 적재는 CDC ClickPipe의 첫 번째 단계로, ClickPipe가 CDC를 시작하기 전에 원본 데이터베이스 테이블의 기존 데이터를 ClickHouse로 동기화합니다. 많은 경우 개발자는 `pg_dump`나 `pg_restore`를 사용하거나, 단일 스레드로 원본 데이터베이스에서 읽어 ClickHouse에 쓰는 등 이 작업을 단일 스레드 방식으로 수행합니다.
하지만 Postgres ClickPipe는 이 과정을 병렬화할 수 있어 초기 적재 속도를 크게 높일 수 있습니다.

<div id="ctid-pg-snapshot">
  ### Postgres의 CTID 컬럼
</div>

Postgres에서는 테이블의 각 행에 CTID라고 하는 고유 식별자가 있습니다. 이는 기본적으로 표시되지 않는 시스템 컬럼이지만, 테이블 내 행을 고유하게 식별하는 데 사용할 수 있습니다. CTID는 블록 번호와 해당 블록 내 오프셋을 조합한 값으로, 이를 통해 행에 효율적으로 접근할 수 있습니다.

<div id="logical-partitioning-pg-snapshot">
  ### 논리적 파티셔닝
</div>

Postgres ClickPipe는 CTID 컬럼을 사용해 원본 테이블을 논리적으로 파티셔닝합니다. 먼저 원본 테이블에서 COUNT(\*)를 수행한 다음, 각 파티션의 CTID 범위를 가져오기 위한 윈도 함수 기반 파티셔닝 쿼리를 실행해 파티션을 계산합니다. 이를 통해 ClickPipe는 원본 테이블을 병렬로 읽을 수 있으며, 각 파티션은 별도의 스레드에서 처리됩니다.

아래 설정을 살펴보겠습니다.

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-3a82795f/a9Bs4XObb7pMATI7/images/integrations/data-ingestion/clickpipes/postgres/snapshot_params.png?fit=max&auto=format&n=a9Bs4XObb7pMATI7&q=85&s=da02785543355607d1b8f59ed7a34b08" alt="스냅샷 매개변수" size="md" width="1192" height="532" data-path="images/integrations/data-ingestion/clickpipes/postgres/snapshot_params.png" />

<div id="numrows-pg-snapshot">
  #### 파티션당 스냅샷 행 수
</div>

이 설정은 파티션을 구성하는 행 수를 제어합니다. ClickPipe는 원본 테이블을 이 크기의 청크로 읽으며, 청크는 설정된 초기 적재 병렬성에 따라 병렬로 처리됩니다. 기본값은 파티션당 100,000행입니다.

<div id="parallelism-pg-snapshot">
  #### 초기 적재 병렬성
</div>

이 설정은 동시에 병렬 처리할 파티션 수를 제어합니다. 기본값은 4이며, ClickPipe가 원본 테이블의 파티션 4개를 병렬로 읽는다는 의미입니다. 초기 적재 속도를 높이기 위해 이 값을 늘릴 수 있지만, 원본 데이터베이스에 과도한 부하가 걸리지 않도록 원본 인스턴스 사양에 맞는 적절한 값으로 유지하는 것이 좋습니다. ClickPipe는 원본 테이블의 크기와 파티션당 행 수를 기준으로 파티션 수를 자동으로 조정합니다.

<div id="tables-parallel-pg-snapshot">
  #### 병렬로 스냅샷할 테이블 수
</div>

병렬 스냅샷과 직접 관련된 설정은 아니지만, 이 설정은 초기 적재 중 동시에 처리할 테이블 수를 제어합니다. 기본값은 1입니다. 이는 파티션 수준의 병렬성에 더해 적용된다는 점에 유의하십시오. 따라서 파티션이 4개이고 테이블이 2개이면 ClickPipe는 8개의 파티션을 병렬로 읽습니다.

<div id="monitoring-parallel-pg-snapshot">
  ### Postgres에서 병렬 스냅샷 모니터링
</div>

**pg\_stat\_activity**를 분석하면 병렬 스냅샷이 실제로 동작하는 모습을 확인할 수 있습니다. ClickPipe는 원본 데이터베이스에 여러 개의 연결을 만들고, 각 연결은 원본 테이블의 서로 다른 파티션을 읽습니다. 서로 다른 CTID 범위를 사용하는 **FETCH** 쿼리가 보이면 ClickPipe가 원본 테이블을 읽고 있다는 뜻입니다. 여기서 COUNT(\*)와 파티셔닝 쿼리도 확인할 수 있습니다.

<div id="limitations-parallel-pg-snapshot">
  ### 제한 사항
</div>

* 파이프를 생성한 후에는 스냅샷 매개변수를 수정할 수 없습니다. 변경하려면 새 ClickPipe를 생성해야 합니다.
* 기존 ClickPipe에 테이블을 추가할 때는 스냅샷 매개변수를 변경할 수 없습니다. 새 테이블에는 기존 매개변수가 적용됩니다.
* partition key 컬럼에는 `NULL` 값이 없어야 합니다. `NULL` 값은 파티셔닝 로직에서 제외됩니다.