> ## 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.

# Documentando sua integração com o ClickHouse

> Como contribuir com páginas de integração para este repositório, incluindo seções obrigatórias e um modelo para copiar e colar.

A documentação de integrações neste site oferece aos usuários finais um único lugar para avaliar e solucionar problemas de configuração. Esta página descreve o que incluir, onde os arquivos devem ser colocados e como abrir um pull request.

Comece com [Criando integrações](/pt-BR/resources/develop-contribute/integrations/building-integrations) e [Testando sua integração](/pt-BR/resources/develop-contribute/integrations/testing-your-integration), se ainda não tiver feito isso.

<div id="where-docs-live">
  ## Onde a documentação está
</div>

* **Repositório:** [`ClickHouse/ClickHouse`](https://github.com/ClickHouse/ClickHouse) (`docs/` nesta árvore)
* **Formato:** MDX, gerado com [Mintlify](https://www.mintlify.com/)
* **Localização:** `docs/integrations/<category>/<your-integration>/`, em que `<category>` reflete o que seu produto faz (`data-visualization`, `data-ingestion`, `language-clients` e assim por diante)
* **Processo:** abra um pull request para a `master`. A equipe de integrações do ClickHouse faz a revisão. Quem contribui pela primeira vez assina o Contributor License Agreement quando o bot solicita no PR. Consulte o [guia de contribuição para a documentação](https://github.com/ClickHouse/ClickHouse/tree/master/docs#readme) para visualizar localmente (`mint dev` a partir de `docs/`)

As páginas de integração neste repositório são a principal referência para os usuários finais. Você pode incluir, na sua página de integração, links para documentação complementar no seu site com detalhes específicos do produto.

Bons exemplos: [Tableau](/pt-BR/integrations/connectors/data-visualization/tableau/tableau-and-clickhouse) e [Metabase](/pt-BR/integrations/connectors/data-visualization/metabase-and-clickhouse).

<div id="choosing-a-category">
  ## Escolhendo uma categoria
</div>

Escolha a categoria que melhor corresponde ao que seu produto faz. Consulte as categorias existentes em [Integrations](/pt-BR/integrations/home) antes de abrir um PR. Se não tiver certeza, informe a categoria proposta na descrição do PR, e a equipe de integrações ajudará a definir onde a página deve ficar.

<div id="required-sections">
  ## Seções obrigatórias
</div>

Toda página de integração deve abordar o seguinte, de preferência nesta ordem:

1. **Objetivo.** Qual problema a integração resolve, em duas ou três frases. Evite texto de marketing. Em geral, os leitores são engenheiros avaliando uma implementação
2. **Pré-requisitos e matriz de versões compatíveis.** O que o usuário precisa ter instalado e quais versões são compatíveis com **ClickHouse Cloud e ambientes self-hosted (open source)**. Uma tabela pequena funciona bem
3. **Passo a passo da configuração.** Instruções passo a passo até obter uma conexão funcional, com **cobertura lado a lado de Cloud e self-hosted** quando houver diferenças (host, porta, TLS)
4. **Autenticação.** Quais modos de autenticação têm suporte (nome de usuário e senha via TLS, no mínimo, além de mTLS, certificado de cliente SSL e observações sobre lista de permissões de IP, se relevante)
5. **Exemplo de ponta a ponta.** Pelo menos um exemplo realista, da conexão até um resultado relevante. Use um [dataset de exemplo do ClickHouse](/pt-BR/get-started/sample-datasets/index) para que os leitores possam reproduzi-lo
6. **Limites conhecidos e características de desempenho.** Lacunas no sistema de tipos, limites de result-set, observações sobre throughput e recursos sem suporte. Ser transparente aqui reduz ciclos de suporte
7. **Solução de problemas.** Erros comuns e suas resoluções. Dois ou três casos frequentes bastam para uma primeira versão

<div id="style-notes">
  ## Observações de estilo
</div>

* **Mostre Cloud e self-hosted.** Cloud normalmente usa HTTPS na porta `8443` e native TCP na `9440`. Self-hosted usa `8123` e `9000` por padrão
* **Use callouts do Mintlify** (`<Note>`, `<Warning>`, `<Tip>`) para observações em vez de parágrafos em negrito
* **Inclua links para mais detalhes.** Use links para a documentação existente sobre tipos de dados, formatos, JDBC, ClickPipes e tópicos semelhantes, em vez de explicá-los novamente
* **Sem marketing.** As páginas de integração aqui são referências técnicas. Conteúdo promocional deve ficar no seu site; podemos incluir um link para ele no diretório de parceiros

<div id="copy-paste-skeleton">
  ## Modelo base para copiar e colar
</div>

Preencha as seções entre colchetes, salve como `docs/integrations/<category>/<your-integration>/index.mdx` e abra um PR.

```mdx theme={null}
---
title: '[Your product] and ClickHouse'
sidebarTitle: '[Your product]'
slug: /integrations/[your-product]
description: '[One sentence: what the integration does.]'
doc_type: 'guide'
keywords: ['[your product]', 'integration']
---

[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].

## Authentication

[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">
  ## Revisão
</div>

A equipe de integrações do ClickHouse revisa os PRs quanto à precisão técnica, à cobertura de Cloud e self-hosted e ao estilo da documentação. Continue iterando no PR até a aprovação dos revisores. Essa aprovação é o requisito para o merge.