partner integration docs v0#6262
Open
mshustov wants to merge 6 commits into
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
4 Skipped Deployments
|
|
Docs PR opened: ClickHouse/mintlify-docs-dev#46 Added a four-page Partner program section guiding partners on building, testing, and documenting ClickHouse integrations. |
Contributor
alexfrancoeur
left a comment
alexfrancoeur
left a comment
There was a problem hiding this comment.
This is amazing, thank you @mshustov 🙏 🙏 🙏 🙏
I dropped in comments that are more around positioning (integration development vs. partner focused) and some others around identification, etc. I think we can probably talk through these things, come to an agreement, and I'm happy to help update the docs based on where we land.
|
|
||
| ## Sandbox and trial access {#sandbox-and-trial-access} | ||
|
|
||
| [ClickHouse Cloud](https://clickhouse.com/cloud) offers a free trial for development and integration validation. Partners enrolled in the formal program receive additional development credits; details will be available in the partner portal. |
Contributor
There was a problem hiding this comment.
@Amehla we should clarify what's available in the partner portal and how much we should lean on this narrative in these docs. My thinking is that we make this more generic vs. pointing to the partner portal. For this one specifically, I think it's fine if we say something like -- "if you are a House Mate and partner, you can get credits in the partner portal"
| | Partner integrations | Built or maintained, and supported by, third-party software vendors | | ||
| | Community integrations | Built or maintained and supported by community members. No direct support is available besides the public GitHub repositories and community Slack channels | | ||
|
|
||
| :::tip Building a partner integration? |
Contributor
There was a problem hiding this comment.
@Amehla we'll need the stubbed link for the partner portal and sign up page
| These guides orient you if you build a product that connects to ClickHouse. They cover the integration surface, how to validate your connector, and how to publish documentation on this site. | ||
|
|
||
| :::note Partner portal | ||
| A dedicated [partner portal](https://clickhouse.com/partners) is launching soon. Until then, use these pages to get started. [Sign up](https://clickhouse.com/partners) when the portal is available to register your integration. |
Contributor
There was a problem hiding this comment.
I think we should just act like it's available today and publish this when it's live. It's only a few days away, but let's confirm with @Amehla
Blargian
approved these changes
May 26, 2026
| If you own the pipeline, use one of the [official language clients](/integrations/language-clients). They handle serialization, batching, TLS, compression, and connection pooling. You pass runtime primitives; the client handles the wire format. | ||
|
|
||
| - Official clients: Python, Go, Java, JavaScript, Rust, C#, C++ | ||
| - Both wire protocols: HTTP and native TCP (Go and C++) |
Member
There was a problem hiding this comment.
Suggested change
| - Both wire protocols: HTTP and native TCP (Go and C++) | |
| - Both wire protocols: HTTP (all clients) and native TCP (Go and C++ clients only) |
|
|
||
| Integration pages in this repository are the primary reference for end users. You can link to supplementary documentation on your site from your integration page for product-specific details. | ||
|
|
||
| Good exemplars: [Tableau](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/integrations/data-visualization/tableau/tableau-and-clickhouse.md) and [Metabase](/integrations/metabase). |
Member
There was a problem hiding this comment.
Suggested change
| Good exemplars: [Tableau](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/integrations/data-visualization/tableau/tableau-and-clickhouse.md) and [Metabase](/integrations/metabase). | |
| Good exemplars: [Tableau](/integrations/tableau) and [Metabase](/integrations/metabase). |
Comment on lines
+15
to
+17
| :::note Partner portal | ||
| A dedicated [partner portal](https://clickhouse.com/partners) is launching soon. Until then, use these pages to get started. [Sign up](https://clickhouse.com/partners) when the [partner portal](https://clickhouse.com/partners) is available to register your integration. | ||
| ::: |
Member
There was a problem hiding this comment.
Suggested change
| :::note Partner portal | |
| A dedicated [partner portal](https://clickhouse.com/partners) is launching soon. Until then, use these pages to get started. [Sign up](https://clickhouse.com/partners) when the [partner portal](https://clickhouse.com/partners) is available to register your integration. | |
| ::: | |
| :::note[Partner portal] | |
| A dedicated [partner portal](https://clickhouse.com/partners) is launching soon. Until then, use these pages to get started. [Sign up](https://clickhouse.com/partners) when the [partner portal](https://clickhouse.com/partners) is available to register your integration. | |
| ::: |
|
|
||
| # Testing your ClickHouse integration | ||
|
|
||
| Validate your integration against both ClickHouse deployment modes and datasets that exercise ClickHouse's type system at meaningful scale before you submit it for review. This page defines what "tested" means at the entry level. Formal validation is a separate process for partners progressing to higher partnership tiers. |
Member
There was a problem hiding this comment.
Suggested change
| Validate your integration against both ClickHouse deployment modes and datasets that exercise ClickHouse's type system at meaningful scale before you submit it for review. This page defines what "tested" means at the entry level. Formal validation is a separate process for partners progressing to higher partnership tiers. | |
| Validate your integration against both ClickHouse deployment modes and datasets that exercise ClickHouse's type system at a meaningful scale before you submit it for review. This page defines what "tested" means at the entry level. Formal validation is a separate process for partners progressing to higher partnership tiers. |
"at a meaningful scale" -> could we link to some guidance here?
Ignore, mentioned below
|
|
||
| **Functional correctness.** Exercise every code path your integration exposes: ingestion, querying, schema discovery, error handling, and reconnection. If your product surfaces SQL to end users, confirm that the queries your UI generates round-trip cleanly. | ||
|
|
||
| **Type-system coverage.** ClickHouse supports arrays, tuples, maps, JSON, nested, LowCardinality, Decimal, Date and DateTime variants, UUID, IPv4 and IPv6, enums, and aggregate-function types. Integrations often hit issues with nested arrays, deeply nested tuples, and JSON columns. Your client library and UI should handle these gracefully. At minimum, fail with a readable error instead of silently truncating or misrendering. |
Member
There was a problem hiding this comment.
Suggested change
| **Type-system coverage.** ClickHouse supports arrays, tuples, maps, JSON, nested, LowCardinality, Decimal, Date and DateTime variants, UUID, IPv4 and IPv6, enums, and aggregate-function types. Integrations often hit issues with nested arrays, deeply nested tuples, and JSON columns. Your client library and UI should handle these gracefully. At minimum, fail with a readable error instead of silently truncating or misrendering. | |
| **Type-system coverage.** ClickHouse supports arrays, tuples, maps, JSON, nested, LowCardinality, Decimal, Date and DateTime variants, UUID, IPv4 and IPv6, enums, and aggregate-function types. Integrations often hit issues with nested arrays, deeply nested tuples, and JSON columns. Your client library and UI should handle these gracefully, and at a minimum, fail with a readable error instead of silently truncating or misrendering. |
|
|
||
| ## Recommended example datasets {#recommended-example-datasets} | ||
|
|
||
| The full set is at [Example datasets](/getting-started/example-datasets). These four cover most integration testing needs: |
Member
There was a problem hiding this comment.
Suggested change
| The full set is at [Example datasets](/getting-started/example-datasets). These four cover most integration testing needs: | |
| The full set can be found in the [**Example datasets**](/getting-started/example-datasets) section. The following four datasets cover most integration testing needs: |
Comment on lines
+25
to
+26
| :::tip Building a ClickHouse integration? | ||
| If you are building a product that connects to ClickHouse, start with the [Integration development](/integrations/integration-development) guides: [building integrations](/integrations/integration-development/building-integrations), [testing](/integrations/integration-development/testing-your-integration), and [documenting your product](/integrations/integration-development/documenting-your-integration). When the [partner portal](https://clickhouse.com/partners) is live, [sign up](https://clickhouse.com/partners) to register your integration. |
Member
There was a problem hiding this comment.
Suggested change
| :::tip Building a ClickHouse integration? | |
| If you are building a product that connects to ClickHouse, start with the [Integration development](/integrations/integration-development) guides: [building integrations](/integrations/integration-development/building-integrations), [testing](/integrations/integration-development/testing-your-integration), and [documenting your product](/integrations/integration-development/documenting-your-integration). When the [partner portal](https://clickhouse.com/partners) is live, [sign up](https://clickhouse.com/partners) to register your integration. | |
| :::tip[Building a ClickHouse integration?] | |
| If you are building a product that connects to ClickHouse, start with the [Integration development](/integrations/integration-development) guides: [building integrations](/integrations/integration-development/building-integrations), [testing](/integrations/integration-development/testing-your-integration), and [documenting your product](/integrations/integration-development/documenting-your-integration). When the [partner portal](https://clickhouse.com/partners) is live, [sign up](https://clickhouse.com/partners) to register your integration. |
Comment on lines
+36
to
+42
| - **Purpose.** What problem the integration solves, in two or three sentences. Avoid marketing copy. Readers are usually engineers scoping a setup | ||
| - **Prerequisites and supported version matrix.** What the user needs installed and which versions you support for **both ClickHouse Cloud and self-hosted (open source)**. A small table works well | ||
| - **Setup walkthrough.** Step-by-step instructions to a working connection, with **side-by-side coverage of Cloud and self-hosted** where they differ (host, port, TLS) | ||
| - **Authentication.** Which auth modes you support (username and password over TLS at minimum, plus mTLS, SSL client cert, IP allow-list notes if relevant) | ||
| - **End-to-end example.** At least one realistic example from connection through a meaningful result. Use a [ClickHouse example dataset](/getting-started/example-datasets) so readers can reproduce it | ||
| - **Known limits and performance characteristics.** Type-system gaps, result-set thresholds, throughput notes, unsupported features. Honesty here saves support cycles | ||
| - **Troubleshooting.** Common errors and resolutions. Two or three frequent cases are enough for a first version |
Member
There was a problem hiding this comment.
Suggested change
| - **Purpose.** What problem the integration solves, in two or three sentences. Avoid marketing copy. Readers are usually engineers scoping a setup | |
| - **Prerequisites and supported version matrix.** What the user needs installed and which versions you support for **both ClickHouse Cloud and self-hosted (open source)**. A small table works well | |
| - **Setup walkthrough.** Step-by-step instructions to a working connection, with **side-by-side coverage of Cloud and self-hosted** where they differ (host, port, TLS) | |
| - **Authentication.** Which auth modes you support (username and password over TLS at minimum, plus mTLS, SSL client cert, IP allow-list notes if relevant) | |
| - **End-to-end example.** At least one realistic example from connection through a meaningful result. Use a [ClickHouse example dataset](/getting-started/example-datasets) so readers can reproduce it | |
| - **Known limits and performance characteristics.** Type-system gaps, result-set thresholds, throughput notes, unsupported features. Honesty here saves support cycles | |
| - **Troubleshooting.** Common errors and resolutions. Two or three frequent cases are enough for a first version | |
| 1. **Purpose.** What problem the integration solves, in two or three sentences. Avoid marketing copy. Readers are usually engineers scoping a setup | |
| 2. **Prerequisites and supported version matrix.** What the user needs installed and which versions you support for **both ClickHouse Cloud and self-hosted (open source)**. A small table works well | |
| 3. **Setup walkthrough.** Step-by-step instructions to a working connection, with **side-by-side coverage of Cloud and self-hosted** where they differ (host, port, TLS) | |
| 4. **Authentication.** Which auth modes you support (username and password over TLS at minimum, plus mTLS, SSL client cert, IP allow-list notes if relevant) | |
| 5. **End-to-end example.** At least one realistic example from connection through a meaningful result. Use a [ClickHouse example dataset](/getting-started/example-datasets) so readers can reproduce it | |
| 6. **Known limits and performance characteristics.** Type-system gaps, result-set thresholds, throughput notes, unsupported features. Honesty here saves support cycles | |
| 7. **Troubleshooting.** Common errors and resolutions. Two or three frequent cases are enough for a first version |
Let's make it a numbered list to emphasise that pages should ideally cover these in this order.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds v0 Partner program documentation for external partners building ClickHouse integrations. This is interim onboarding content until a dedicated partner portal launches at the upcoming event.
New section at /integrations/partners with four pages:
Navigation: new Partner program sidebar category under Integrations; tip callout on the Integrations landing page pointing partners to the guides
Note
Low Risk
Documentation and navigation only; no runtime, auth, or data-path changes.
Overview
Adds interim Integration development partner onboarding under
/integrations/integration-developmentuntil the partner portal ships.The Integrations landing page gets a
:::tipthat points builders to the three guides and clickhouse.com/partners. sidebars.js adds a collapsed Integration development category (overview, building, testing, documenting).New content covers ingestion (ClickPipes vs language clients), consumption and result-set sizing, User-Agent conventions, Cloud + OSS testing matrices and example datasets, and how to contribute product pages to
clickhouse-docs(required sections + PR skeleton).Reviewed by Cursor Bugbot for commit e1745b5. Bugbot is set up for automated code reviews on this repo. Configure here.