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

# ClickHouse 통합 문서 작성하기

> 필수 섹션과 복사해 붙여넣을 수 있는 골격을 포함하여 clickhouse-docs에 통합 페이지를 기여하는 방법을 설명합니다.

이 사이트의 통합 문서는 최종 사용자가 설정 범위를 파악하고 문제를 해결하는 데 필요한 정보를 한곳에서 찾을 수 있도록 합니다. 이 페이지에서는 포함해야 할 내용, 파일의 위치, 그리고 Pull Request를 여는 방법을 설명합니다.

아직 확인하지 않았다면 먼저 [Building integrations](/ko/resources/develop-contribute/integrations/building-integrations)와 [Testing your integration](/ko/resources/develop-contribute/integrations/testing-your-integration)을 살펴보세요.

<div id="where-docs-live">
  ## 문서가 있는 위치
</div>

* **리포지토리:** [`ClickHouse/clickhouse-docs`](https://github.com/ClickHouse/clickhouse-docs)
* **형식:** Markdown, Docusaurus로 빌드
* **위치:** `/docs/integrations/<category>/<your-integration>/`, 여기서 `<category>`는 제품이 수행하는 역할을 반영합니다 (`data-visualization`, `data-ingestion`, `language-clients` 등)
* **절차:** `main` 브랜치를 대상으로 pull request를 생성하십시오. ClickHouse 통합 팀이 검토합니다. 처음 기여하는 경우 PR에서 봇이 안내하면 Contributor License Agreement에 서명합니다

이 리포지토리의 통합 페이지는 최종 사용자를 위한 주요 참고 자료입니다. 제품별 세부 정보는 통합 페이지에서 사이트의 보조 문서로 링크할 수 있습니다.

좋은 예시: [Tableau](/ko/integrations/connectors/data-visualization/tableau/tableau-and-clickhouse) 및 [Metabase](/ko/integrations/connectors/data-visualization/metabase-and-clickhouse).

<div id="choosing-a-category">
  ## 카테고리 선택하기
</div>

제품의 기능에 가장 잘 맞는 카테고리를 선택합니다. PR을 열기 전에 [Integrations](/ko/integrations/home)의 기존 카테고리를 먼저 살펴보십시오. 확신이 서지 않으면 PR 설명에 제안하는 카테고리를 적어 두십시오. 그러면 통합 팀이 해당 페이지의 적절한 위치를 정하는 데 도움을 드립니다.

<div id="required-sections">
  ## 필수 섹션
</div>

모든 통합 페이지는 가능하면 다음 내용을 이 순서대로 다루어야 합니다:

1. **목적.** 통합이 어떤 문제를 해결하는지 2\~3문장으로 설명합니다. 마케팅성 문구는 피하십시오. 독자는 대개 도입 범위를 검토하는 엔지니어입니다
2. **사전 요구 사항 및 지원 버전 매트릭스.** **ClickHouse Cloud와 자체 호스팅(오픈 소스) 모두에 대해** 무엇을 설치해야 하는지와 어떤 버전을 지원하는지 설명합니다. 작은 표를 사용하는 것이 좋습니다
3. **설정 안내.** 실제로 연결이 동작할 때까지의 단계별 지침을 제공합니다. 차이가 있는 경우 **Cloud와 자체 호스팅을 나란히 비교해** 설명하십시오(호스트, 포트, TLS)
4. **인증(authentication).** 지원하는 인증 방식을 설명합니다(TLS를 통한 사용자 이름 및 비밀번호는 최소 요구 사항이며, 해당하는 경우 mTLS, SSL 클라이언트 인증서, IP 허용 목록 관련 참고 사항도 포함)
5. **엔드투엔드 예시.** 연결부터 의미 있는 결과까지 이어지는 현실적인 예시를 최소 1개 포함합니다. 독자가 재현할 수 있도록 [ClickHouse 예시 데이터셋](/ko/get-started/sample-datasets)을 사용하십시오
6. **알려진 제한 사항 및 성능 특성.** 타입 시스템의 한계, 결과 집합 임계값, 처리량 관련 참고 사항, 지원되지 않는 기능을 설명합니다. 이 부분을 솔직하게 작성하면 지원 부담을 줄일 수 있습니다
7. **문제 해결.** 자주 발생하는 오류와 해결 방법을 설명합니다. 첫 번째 버전에서는 흔한 사례 2\~3개면 충분합니다

<div id="style-notes">
  ## 스타일 참고 사항
</div>

* **Cloud와 자체 호스팅을 모두 포함하세요.** Cloud는 일반적으로 포트 `8443`에서 HTTPS를, `9440`에서 네이티브 TCP를 사용합니다. 자체 호스팅의 기본 포트는 `8123`과 `9000`입니다
* **굵은 문단 대신 Docusaurus admonitions** (`:::note`, `:::warning`, `:::tip`)를 **콜아웃에 사용하세요**
* **자세한 내용은 링크로 안내하세요.** 데이터 타입, 포맷, JDBC, ClickPipes 같은 주제는 다시 설명하지 말고 기존 문서로 연결하세요
* **마케팅성 내용은 제외하세요.** 여기의 통합 페이지는 기술 참고 문서입니다. 홍보성 콘텐츠는 별도 사이트에 두고, 파트너 디렉터리에서 해당 콘텐츠로 링크할 수 있습니다

<div id="copy-paste-skeleton">
  ## 복사해 붙여넣는 템플릿
</div>

대괄호로 표시된 부분을 채우고 `/docs/integrations/<category>/<your-integration>/index.md`로 저장한 다음 PR을 여십시오.

```markdown theme={null}
# [Your product] and ClickHouse

[One to three sentences: what the integration does and why a
ClickHouse user would want it.]

## Prerequisites

- [Your product, version X.Y or later]
- ClickHouse Cloud, or self-hosted ClickHouse version [X.Y] or later
- [Anything else: driver, plugin, network access requirements]

### Version matrix

| [Your product] | ClickHouse Cloud | ClickHouse open source | Notes    |
| -------------- | ---------------- | ---------------------- | -------- |
| X.Y            | ✅               | ✅ 24.x+               | [if any] |

## Setup

### Connect to ClickHouse Cloud

1. In the ClickHouse Cloud console, select your service and click **Connect**.
2. Choose **HTTPS**. Copy the host, port (8443), username, and password.
3. In [your product], [steps to configure the connection].

### Connect to self-hosted ClickHouse

1. [How to point at a self-hosted instance — host, port 8123 or 9000, TLS notes.]
2. In [your product], [steps to configure the connection].

## 인증

[List supported auth modes — username/password over TLS, mTLS, etc. — and how
to configure each.]

## Example: querying the [dataset] dataset

[Walkthrough using one of the ClickHouse example datasets, end-to-end.]

## Known limits

- [Types not yet supported, e.g., deeply nested JSON]
- [Result-set size thresholds or other performance notes]
- [Feature gaps]

## Troubleshooting

### [Common error message]

[Cause and resolution.]

### [Another common error]

[Cause and resolution.]
```

<div id="review">
  ## 검토
</div>

ClickHouse 통합 팀은 PR의 기술적 정확성, Cloud 및 자체 호스팅 지원 범위, 문서 스타일을 검토합니다. 검토자가 승인할 때까지 PR에서 수정과 보완을 반복하십시오. 이 승인이 머지 조건입니다.