Documentando sua integração com o ClickHouse

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 e Testando sua integração, se ainda não tiver feito isso.

• Repositório: ClickHouse/ClickHouse (docs/ nesta árvore)
• Formato: MDX, gerado com Mintlify
• 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 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 e Metabase.

Escolha a categoria que melhor corresponde ao que seu produto faz. Consulte as categorias existentes em Integrations 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.

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

• 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

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

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

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.