Skip to main content

Documentation Index

Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-44cf2c7c.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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. See Building integrations for ingestion and consumption paths, and Documenting your integration for how to publish your results.

​
Test matrix

Cover both deployment modes. Most customers run one or the other, and behavior differs in places (auth, networking, available features).
  • ClickHouse Cloud: sign up for a free trial. No credit card is required for the development tier
  • Self-hosted (OSS): use the latest stable release from GitHub releases. The install guide is the fastest path to a local instance with Docker
Test against both, and document any feature gaps in your integration page.

​
What to test

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. Partners 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. Scale. Test at result-set sizes and row counts your customers will run. For user-facing BI, that often means tables with hundreds of millions to billions of rows, and result sets from single aggregates to tens of thousands of rows. Unbounded reads (SELECT *) should fail predictably or paginate, not hang. Authentication. Validate at least one TLS-enabled connection. If you expose auth configuration, test every mode you document (username and password over TLS, mTLS, SSL client certificate). Connection lifecycle. Confirm sane behavior on dropped connections, server restarts, and slow queries. Many escalations trace back to connection handling rather than query semantics. The full set is at Example datasets. These four cover most partner testing needs:
  • GitHub events: 3.1B rows with nested event payloads. Best for arrays, tuples, and nested types
  • NYC taxi data: billions of rows with a well-known schema. Good for throughput and read-path testing
  • Stack Overflow: multi-table relational data for JOIN-heavy BI scenarios
  • Hacker News: 28M rows, fast to load, useful for iteration
For extreme-scale validation, use WikiStat (~0.5 trillion records).

​
What to capture from your testing

When you submit your integration for review, share:
  • ClickHouse versions tested (Cloud and OSS)
  • Datasets and approximate scale (rows, on-disk size)
  • Types your integration handles and types it does not (this becomes the Known limits section of your docs)
  • Performance characteristics worth flagging, such as result-set thresholds where behavior changes
A short test report saves review cycles. A paragraph plus a table is enough.