> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> Google Dataflow Template를 사용해 BigQuery의 데이터를 ClickHouse로 수집할 수 있습니다

# Dataflow BigQuery-ClickHouse Template

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

BigQuery에서 ClickHouse로 전송하는 Template은 BigQuery 테이블의 데이터를 ClickHouse 테이블로 수집하는 배치 파이프라인입니다.
이 Template은 전체 테이블을 읽거나, 제공된 SQL 쿼리를 사용해 특정 레코드만 필터링할 수 있습니다.

<div id="pipeline-requirements">
  ## 파이프라인 요구 사항
</div>

* 소스 BigQuery 테이블이 존재해야 합니다.
* 대상 ClickHouse 테이블이 존재해야 합니다.
* Dataflow 워커 머신이 ClickHouse 호스트에 접근할 수 있어야 합니다.

<div id="template-parameters">
  ## Template 매개변수
</div>

<br />

<br />

| Parameter Name          | Parameter Description                                                                                                                                                                                                                                              | Required | Notes                                                                                                                                                                                                                            |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jdbcUrl`               | `jdbc:clickhouse://<host>:<port>/<schema>` 형식의 ClickHouse JDBC URL입니다.                                                                                                                                                                                             | ✅        | 사용자 이름과 비밀번호는 JDBC 옵션으로 추가하지 마십시오. 그 밖의 JDBC 옵션은 JDBC URL 끝에 추가할 수 있습니다. ClickHouse Cloud 사용자는 `jdbcUrl`에 `ssl=true&sslmode=NONE`을 추가하십시오.                                                                                       |
| `clickHouseUsername`    | 인증에 사용할 ClickHouse 사용자 이름입니다.                                                                                                                                                                                                                                      | ✅        |                                                                                                                                                                                                                                  |
| `clickHousePassword`    | 인증에 사용할 ClickHouse 비밀번호입니다.                                                                                                                                                                                                                                        | ✅        |                                                                                                                                                                                                                                  |
| `clickHouseTable`       | 데이터가 삽입될 대상 ClickHouse 테이블입니다.                                                                                                                                                                                                                                     | ✅        |                                                                                                                                                                                                                                  |
| `maxInsertBlockSize`    | 삽입용 블록 생성 방식을 제어하는 경우, 삽입을 위한 최대 블록 크기입니다. (`ClickHouseIO` 옵션)                                                                                                                                                                                                     |          | `ClickHouseIO` 옵션입니다.                                                                                                                                                                                                            |
| `insertDistributedSync` | 이 설정을 활성화하면 분산 테이블에 대한 INSERT 쿼리는 데이터가 클러스터의 모든 노드로 전송될 때까지 대기합니다. (`ClickHouseIO` 옵션)                                                                                                                                                                             |          | `ClickHouseIO` 옵션입니다.                                                                                                                                                                                                            |
| `insertQuorum`          | 복제된 테이블(Replicated Table)의 INSERT 쿼리에서 지정한 수의 레플리카에 대한 쓰기가 완료될 때까지 대기하고, 데이터 추가를 선형화합니다. 0 - 비활성화.                                                                                                                                                                 |          | `ClickHouseIO` 옵션입니다. 이 설정은 기본 서버 설정에서 비활성화되어 있습니다.                                                                                                                                                                              |
| `insertDeduplicate`     | 복제된 테이블(Replicated Table)의 INSERT 쿼리에서 삽입되는 블록에 대해 중복 제거를 수행할지 지정합니다.                                                                                                                                                                                              |          | `ClickHouseIO` 옵션입니다.                                                                                                                                                                                                            |
| `maxRetries`            | 삽입당 최대 재시도 횟수입니다.                                                                                                                                                                                                                                                  |          | `ClickHouseIO` 옵션입니다.                                                                                                                                                                                                            |
| `InputTableSpec`        | 읽어올 BigQuery 테이블입니다. `inputTableSpec` 또는 `query` 중 하나를 지정하십시오. 둘 다 설정하면 `query` 매개변수가 우선합니다. 예시: `<BIGQUERY_PROJECT>:<DATASET_NAME>.<INPUT_TABLE>`.                                                                                                                |          | [BigQuery Storage Read API](https://cloud.google.com/bigquery/docs/reference/storage)를 사용해 BigQuery 스토리지에서 직접 데이터를 읽습니다. [Storage Read API 제한 사항](https://cloud.google.com/bigquery/docs/reference/storage#limitations)을 확인하십시오. |
| `outputDeadletterTable` | 출력 테이블에 기록되지 못한 메시지를 저장하는 BigQuery 테이블입니다. 테이블이 없으면 파이프라인 실행 중에 생성됩니다. 지정하지 않으면 `<outputTableSpec>_error_records`가 사용됩니다. 예를 들어 `<PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>`입니다.                                                                               |          |                                                                                                                                                                                                                                  |
| `query`                 | BigQuery에서 데이터를 읽는 데 사용할 SQL 쿼리입니다. BigQuery 데이터셋이 Dataflow 작업과 다른 프로젝트에 있는 경우 SQL 쿼리에서 전체 데이터셋 이름을 지정하십시오. 예: `<PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>`. `useLegacySql`이 true가 아니면 기본값은 [GoogleSQL](https://cloud.google.com/bigquery/docs/introduction-sql)입니다. |          | `inputTableSpec` 또는 `query` 중 하나를 반드시 지정해야 합니다. 두 매개변수를 모두 설정하면 템플릿은 `query` 매개변수를 사용합니다. 예시: `SELECT * FROM sampledb.sample_table`.                                                                                             |
| `useLegacySql`          | 레거시 SQL을 사용하려면 `true`로 설정합니다. 이 매개변수는 `query` 매개변수를 사용할 때만 적용됩니다. 기본값은 `false`입니다.                                                                                                                                                                                 |          |                                                                                                                                                                                                                                  |
| `queryLocation`         | 기본 테이블에 대한 권한 없이 승인된 뷰에서 읽을 때 필요합니다. 예: `US`.                                                                                                                                                                                                                      |          |                                                                                                                                                                                                                                  |
| `queryTempDataset`      | 쿼리 결과를 저장할 임시 테이블을 생성할 기존 데이터셋을 설정합니다. 예: `temp_dataset`.                                                                                                                                                                                                          |          |                                                                                                                                                                                                                                  |
| `KMSEncryptionKey`      | 쿼리 소스를 사용해 BigQuery에서 읽는 경우, 생성되는 임시 테이블을 암호화하는 데 이 Cloud KMS 키를 사용합니다. 예: `projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key`.                                                                                                     |          |                                                                                                                                                                                                                                  |

<Note>
  모든 `ClickHouseIO` 매개변수의 기본값은 [`ClickHouseIO` Apache Beam 커넥터](/docs/ko/integrations/connectors/data-ingestion/etl-tools/apache-beam#clickhouseiowrite-parameters)에서 확인할 수 있습니다.
</Note>

<div id="source-and-target-tables-schema">
  ## 소스 및 대상 테이블 스키마
</div>

BigQuery 데이터셋을 ClickHouse에 효과적으로 적재하기 위해 파이프라인은 다음 단계로 컬럼 추론 과정을 수행합니다:

1. Template는 대상 ClickHouse 테이블을 기준으로 스키마 객체를 생성합니다.
2. Template는 BigQuery 데이터셋을 순회하며 컬럼 이름을 기준으로 일치하는 컬럼을 찾습니다.

<br />

<Warning>
  다만 BigQuery 데이터셋(테이블 또는 쿼리)의 컬럼 이름은 ClickHouse 대상 테이블의 컬럼 이름과 정확히 동일해야 합니다.
</Warning>

<div id="data-types-mapping">
  ## 데이터 타입 매핑
</div>

BigQuery 타입은 ClickHouse 테이블 정의에 따라 변환됩니다. 따라서 위 표에는 대상 ClickHouse 테이블에 권장되는 매핑이 나와 있습니다(해당 BigQuery 테이블/쿼리 기준).

| BigQuery Type                                                                                                      | ClickHouse Type                                      | Notes                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**배열 타입**](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#array_type)                   | [**배열 타입**](/docs/ko/reference/data-types/array)          | 내부 타입은 이 표에 나열된 지원되는 기본 데이터 타입 중 하나여야 합니다.                                                                                                                                                                                                                                                                                  |
| [**불리언 타입**](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#boolean_type)                | [**Bool 타입**](/docs/ko/reference/data-types/boolean)      |                                                                                                                                                                                                                                                                                                                             |
| [**날짜 타입**](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#date_type)                    | [**Date 타입**](/docs/ko/reference/data-types/date)         |                                                                                                                                                                                                                                                                                                                             |
| [**Datetime 타입**](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#datetime_type)          | [**Datetime 타입**](/docs/ko/reference/data-types/datetime) | `Enum8`, `Enum16`, `FixedString`에도 사용할 수 있습니다.                                                                                                                                                                                                                                                                              |
| [**String 타입**](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#string_type)              | [**String 타입**](/docs/ko/reference/data-types/string)     | BigQuery에서는 모든 Int 타입(`INT`, `SMALLINT`, `INTEGER`, `BIGINT`, `TINYINT`, `BYTEINT`)이 `INT64`의 별칭입니다. Template은 정의된 컬럼 타입(`Int8`, `Int16`, `Int32`, `Int64`)에 따라 컬럼을 변환하므로, ClickHouse에서는 적절한 Integer 크기를 설정하는 것이 좋습니다.                                                                                                      |
| [**Numeric - Integer 타입**](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#numeric_types) | [**Integer 타입**](/docs/ko/reference/data-types/int-uint)  | BigQuery에서는 모든 Int 타입(`INT`, `SMALLINT`, `INTEGER`, `BIGINT`, `TINYINT`, `BYTEINT`)이 `INT64`의 별칭입니다. Template은 정의된 컬럼 타입(`Int8`, `Int16`, `Int32`, `Int64`)에 따라 컬럼을 변환하므로, ClickHouse에서는 적절한 Integer 크기를 설정하는 것이 좋습니다. 또한 ClickHouse 테이블에서 `UInt8`, `UInt16`, `UInt32`, `UInt64`와 같은 부호 없는 Int 타입을 사용하는 경우에도 템플릿이 이를 변환합니다. |
| [**Numeric - Float 타입**](https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types#numeric_types)   | [**Float 타입**](/docs/ko/reference/data-types/float)       | 지원되는 ClickHouse 타입: `Float32` 및 `Float64`                                                                                                                                                                                                                                                                                   |

<div id="running-the-template">
  ## Template 실행
</div>

BigQuery to ClickHouse Template는 Google Cloud CLI를 통해 실행할 수 있습니다.

<Note>
  이 문서, 특히 위 섹션을 반드시 검토하여 Template의 구성 요구 사항과 사전 요구 사항을 충분히 이해하십시오.
</Note>

<Tabs>
  <Tab title="Google Cloud Console">
    Google Cloud Console에 로그인한 다음 DataFlow를 검색합니다.

    1. `CREATE JOB FROM TEMPLATE` 버튼을 클릭합니다.
           <Image img="https://mintcdn.com/private-7c7dfe99/pIetLsS_hOGHqoPJ/images/integrations/data-ingestion/google-dataflow/create_job_from_template_button.webp?fit=max&auto=format&n=pIetLsS_hOGHqoPJ&q=85&s=ca429a13d8a9e99c43ae477bf14ad1a9" border alt="DataFlow 콘솔" width="1872" height="886" data-path="images/integrations/data-ingestion/google-dataflow/create_job_from_template_button.webp" />
    2. Template 양식이 열리면 작업 이름을 입력하고 원하는 리전을 선택합니다.
           <Image img="https://mintcdn.com/private-7c7dfe99/pIetLsS_hOGHqoPJ/images/integrations/data-ingestion/google-dataflow/template_initial_form.webp?fit=max&auto=format&n=pIetLsS_hOGHqoPJ&q=85&s=740afe5c75d840932c0a1071ec2e4e9c" border alt="DataFlow Template 초기 양식" width="1284" height="680" data-path="images/integrations/data-ingestion/google-dataflow/template_initial_form.webp" />
    3. `DataFlow Template` 입력란에 `ClickHouse` 또는 `BigQuery`를 입력한 다음 `BigQuery to ClickHouse` Template를 선택합니다.
           <Image img="https://mintcdn.com/private-7c7dfe99/pIetLsS_hOGHqoPJ/images/integrations/data-ingestion/google-dataflow/template_clickhouse_search.webp?fit=max&auto=format&n=pIetLsS_hOGHqoPJ&q=85&s=ce42d64ae501b16d2eda4435a6d6b755" border alt="BigQuery to ClickHouse Template 선택" width="1370" height="698" data-path="images/integrations/data-ingestion/google-dataflow/template_clickhouse_search.webp" />
    4. Template를 선택하면 양식이 확장되어 다음과 같은 추가 정보를 입력할 수 있습니다.
       * `jdbc:clickhouse://host:port/schema` 형식의 ClickHouse 서버 JDBC URL
       * ClickHouse 사용자 이름
       * ClickHouse 대상 테이블 이름

    <br />

    <Note>
      ClickHouse 비밀번호 옵션은 비밀번호가 구성되지 않은 경우를 위해 선택 사항으로 표시됩니다.
      추가하려면 아래로 스크롤하여 `Password for ClickHouse Endpoint` 옵션으로 이동하십시오.
    </Note>

    <Image img="https://mintcdn.com/private-7c7dfe99/pIetLsS_hOGHqoPJ/images/integrations/data-ingestion/google-dataflow/extended_template_form.webp?fit=max&auto=format&n=pIetLsS_hOGHqoPJ&q=85&s=c070559675a9e221413cb0e69408dbde" border alt="BigQuery to ClickHouse 확장 Template 양식" width="1903" height="864" data-path="images/integrations/data-ingestion/google-dataflow/extended_template_form.webp" />

    5. [Template Parameters](#template-parameters) 섹션에 설명된 대로 BigQuery/ClickHouseIO 관련 구성을 필요에 맞게 사용자 지정하여 추가합니다.
  </Tab>

  <Tab title="Google Cloud CLI">
    ### `gcloud` CLI 설치 및 구성

    * 아직 설치하지 않았다면 [`gcloud` CLI](https://cloud.google.com/sdk/docs/install)를 설치합니다.
    * [이 가이드](https://cloud.google.com/dataflow/docs/guides/templates/using-flex-templates#before-you-begin)의 `Before you begin` 섹션에 따라 DataFlow Template 실행에 필요한 구성, 설정, 권한을 준비합니다.

    ### 명령 실행

    Flex Template를 사용하는 Dataflow 작업을 실행하려면 [`gcloud dataflow flex-template run`](https://cloud.google.com/sdk/gcloud/reference/dataflow/flex-template/run) 명령을 사용합니다.

    아래는 명령 예시입니다.

    ```bash theme={null}
    gcloud dataflow flex-template run "bigquery-clickhouse-dataflow-$(date +%Y%m%d-%H%M%S)" \
     --template-file-gcs-location "gs://clickhouse-dataflow-templates/bigquery-clickhouse-metadata.json" \
     --parameters inputTableSpec="<bigquery table id>",jdbcUrl="jdbc:clickhouse://<clickhouse host>:<clickhouse port>/<schema>?ssl=true&sslmode=NONE",clickHouseUsername="<username>",clickHousePassword="<password>",clickHouseTable="<clickhouse target table>"
    ```

    ### 명령 설명

    * **Job Name:** `run` 키워드 뒤의 텍스트는 고유한 작업 이름입니다.
    * **Template File:** `--template-file-gcs-location`으로 지정한 JSON 파일은 Template 구조와 허용되는 매개변수에 대한 세부 정보를 정의합니다. 언급된 파일 경로는 공개되어 있으며 바로 사용할 수 있습니다.
    * **Parameters:** 매개변수는 쉼표로 구분됩니다. 문자열 기반 매개변수의 경우 값은 큰따옴표로 묶으십시오.

    ### 예상 응답

    명령을 실행한 후에는 다음과 유사한 응답이 표시됩니다.

    ```bash theme={null}
    job:
      createTime: '2025-01-26T14:34:04.608442Z'
      currentStateTime: '1970-01-01T00:00:00Z'
      id: 2025-01-26_06_34_03-13881126003586053150
      location: us-central1
      name: bigquery-clickhouse-dataflow-20250126-153400
      projectId: ch-integrations
      startTime: '2025-01-26T14:34:04.608442Z'
    ```
  </Tab>
</Tabs>

<div id="monitor-the-job">
  ### 작업 모니터링
</div>

Google Cloud Console의 [Dataflow Jobs 탭](https://console.cloud.google.com/dataflow/jobs)으로 이동하여
작업 상태를 모니터링합니다. 진행 상황과 오류를 포함한 작업 세부 정보를 확인할 수 있습니다:

<Image img="https://mintcdn.com/private-7c7dfe99/pIetLsS_hOGHqoPJ/images/integrations/data-ingestion/google-dataflow/dataflow-inqueue-job.webp?fit=max&auto=format&n=pIetLsS_hOGHqoPJ&q=85&s=adf4aca711a2783a0bb1062e9051ec41" size="lg" border alt="실행 중인 BigQuery-ClickHouse 작업을 보여주는 Dataflow 콘솔" width="1668" height="202" data-path="images/integrations/data-ingestion/google-dataflow/dataflow-inqueue-job.webp" />

<div id="troubleshooting">
  ## 문제 해결
</div>

<div id="code-241-dbexception-memory-limit-total-exceeded">
  ### 메모리 제한(전체) 초과 오류(코드 241)
</div>

이 오류는 ClickHouse가 대량의 데이터 배치를 처리하는 중 메모리가 부족할 때 발생합니다. 이 문제를 해결하려면 다음을 수행하세요.

* 인스턴스 리소스를 늘리세요: 데이터 처리 부하를 감당할 수 있도록 메모리가 더 많은 상위 인스턴스로 ClickHouse 서버를 업그레이드하십시오.
* 배치 크기를 줄이세요: Dataflow 작업 구성에서 배치 크기를 조정해 더 작은 데이터 청크를 ClickHouse로 전송하면 배치당 메모리 사용량을 줄일 수 있습니다. 이러한 변경은 데이터 수집 중 리소스 사용량의 균형을 맞추는 데 도움이 됩니다.

<div id="template-source-code">
  ## Template 소스 코드
</div>

Template의 소스 코드는 다음 리포지토리에서 확인할 수 있습니다:

* [`GoogleCloudPlatform/DataflowTemplates`](https://github.com/GoogleCloudPlatform/DataflowTemplates/tree/main/v2/googlecloud-to-clickhouse) — 원본 Google Cloud Platform 리포지토리입니다.
* [`ClickHouse/DataflowTemplates`](https://github.com/ClickHouse/DataflowTemplates) — ClickHouse의 포크 리포지토리입니다.