[fivetran] Revamp docs by koletzilla · Pull Request #5777 · ClickHouse/clickhouse-docs

koletzilla · 2026-03-18T18:49:18Z

Revamp Fivetran docs:

Index cover more details about the current version and related files
Reference covers all the docs we have in Fivetran side: configurations, table engine details...
- I have not moved the full setup-guide, only the configurations details. The full guide should be kept complete in Fivetran side as it's really nice to have it when editing the connector.
Troubleshooting contains usual errors with possible solutions, good practices and some examples to help debugging.

vercel · 2026-03-18T18:49:25Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clickhouse-docs	Ready	Preview, Comment	Mar 24, 2026 10:08am
clickhouse-docs-jp	Building	Preview, Comment	Mar 24, 2026 10:08am

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
clickhouse-docs-ko	Ignored	Preview	Mar 24, 2026 10:08am
clickhouse-docs-ru	Ignored	Preview	Mar 24, 2026 10:08am
clickhouse-docs-zh	Ignored	Preview	Mar 24, 2026 10:08am

dhtclk

Just a few minor nits on voice and grammar, as well as the use of the note admonition.

docs/integrations/data-ingestion/etl-tools/fivetran/index.md

docs/integrations/data-ingestion/etl-tools/fivetran/reference.md

docs/integrations/data-ingestion/etl-tools/fivetran/index.md

docs/integrations/data-ingestion/etl-tools/fivetran/troubleshooting.md

Co-authored-by: Dominic Tran <dominic.tran@clickhouse.com>

…oting.md Co-authored-by: Dominic Tran <dominic.tran@clickhouse.com>

koletzilla · 2026-03-24T09:48:25Z

Thanks for all these suggested changes @dhtclk 🙇

BentsiLeviav · 2026-03-24T15:38:28Z

docs/integrations/data-ingestion/etl-tools/fivetran/reference.md

+| LOCALDATE | [Date](/sql-reference/data-types/date) |
+| LOCALDATETIME | [DateTime](/sql-reference/data-types/datetime) |


I see in the code that these two are targeting Date32 and DateTime64(0, 'UTC') (cover wider values):
https://github.com/ClickHouse/clickhouse-fivetran-destination/blob/6d60da9c7fad3e230871323ba371178565aa9a16/destination/common/data_types/data_types.go#L38
referring to https://github.com/ClickHouse/clickhouse-fivetran-destination/blob/6d60da9c7fad3e230871323ba371178565aa9a16/destination/common/constants/constants.go#L22

Good point! clarifying it now

BentsiLeviav · 2026-03-24T15:41:57Z

docs/integrations/data-ingestion/etl-tools/fivetran/reference.md

+| STRING | [String](/sql-reference/data-types/string) |
+| BINARY | [String](/sql-reference/data-types/string) \* |
+| XML | [String](/sql-reference/data-types/string) \* |
+| JSON | [String](/sql-reference/data-types/string) \* |


I see Time type is missing (https://github.com/ClickHouse/clickhouse-fivetran-destination/blob/6d60da9c7fad3e230871323ba371178565aa9a16/destination/common/data_types/data_types.go#L54) - can you add it + create a follow-up issue in the repo to support it https://clickhouse.com/docs/sql-reference/data-types/time

Adding it to the docs. Looks like we already have an issue to cover it implementation: ClickHouse/clickhouse-fivetran-destination#15

I have extended the issue description with more details

BentsiLeviav · 2026-03-24T15:49:11Z

docs/integrations/data-ingestion/etl-tools/fivetran/reference.md

+
+The Fivetran ClickHouse destination maps [Fivetran data types](https://fivetran.com/docs/destinations#datatypes) to ClickHouse types as follows:
+
+| Fivetran type | ClickHouse type |


For all the date-related types, could you please verify that the range is aligned with Fivetran and the Go client? If it is not, I believe the range is silently replaced with the nearest boundary value

uops, yes, it's. I see some differences. Adding it to the docs

BentsiLeviav · 2026-03-24T16:07:29Z

docs/integrations/data-ingestion/etl-tools/fivetran/reference.md

+| `write_batch_size` | integer | `100000` | 5,000 – 100,000 | Number of rows per batch for insert, update, and replace operations. |
+| `select_batch_size` | integer | `1500` | 200 – 1,500 | Number of rows per batch for SELECT queries used during updates. |
+| `mutation_batch_size` | integer | `1500` | 200 – 1,500 | Number of rows per batch for ALTER TABLE UPDATE mutations in history mode. Lower it if you are experiencing large SQL statements. |
+| `hard_delete_batch_size` | integer | `1500` | 200 – 1,500 | Number of rows per batch for hard delete operations in history mode. Lower it if you are experiencing large SQL statements. |


I see hard_delete_batch_size controls batch size for hard deletes in both standard syncs and history mode.

WriteBatch calls processDeleteFiles calls conn.HardDelete calls reader.ReadBatch(*flags.HardDeleteBatchSize)

BentsiLeviav

Left a few comments/questions.
In addition, can we go over the code and track errors we raise, and document them with an explanation in the troubleshooting guide? (if they are not here already)

BentsiLeviav · 2026-03-24T16:22:20Z

docs/integrations/data-ingestion/etl-tools/fivetran/reference.md

+
+`SharedReplacingMergeTree` performs background data deduplication
+[only during merges at an unknown time](/engines/table-engines/mergetree-family/replacingmergetree).
+However, selecting the latest version of the data without duplicates ad-hoc is possible with the `FINAL` keyword and


Should we warn that FINA can be significantly slower on large tables?
In addition, do you think we might be able to overcome duplicates using MV, not 100% sure, but something like:

-- MV that feeds it CREATE MATERIALIZED VIEW analytics.orders_mv TO analytics.orders_latest AS SELECT * FROM fivetran_schema.orders WHERE _fivetran_deleted = false;

BentsiLeviav · 2026-03-24T16:43:58Z

docs/integrations/data-ingestion/etl-tools/fivetran/troubleshooting.md

+
+### Ensure cluster health during syncs {#cluster-health}
+
+The Fivetran destination checks that all replicas are active before performing operations. If any replica is offline, operations fail after retrying for up to 600 seconds.


IIRC that was (partially) changed.

WaitAllNodesAvailable runs before mutations and is a monitoring/warning step. If replicas aren't all up, it logs a warning but does not block the operation. https://github.com/ClickHouse/clickhouse-fivetran-destination/blob/904aef0da7f0815d75032224f43f24a6ae80b6f0/destination/db/clickhouse.go#L946

WaitAllMutationsCompleted is the one that actually retries for up to 600s, but only when code 341 is received after the mutation itself.

koletzilla changed the title ~~Revamp Fiventran docs~~ [fivetran] Revamp docs Mar 18, 2026

vercel bot had a problem deploying to Preview – clickhouse-docs March 18, 2026 18:50 Failure

vercel bot had a problem deploying to Preview – clickhouse-docs March 19, 2026 10:49 Failure

vercel bot deployed to Preview – clickhouse-docs March 19, 2026 14:21 View deployment

koletzilla added 5 commits March 20, 2026 19:41

first version for the draft

3edd461

Improve index.html, fix links, fix lint

9b7d97c

lint

d7ad917

Finish docs. Remove setup-guide to let that live in Fivetran side

161d002

lint

659f3d2

koletzilla force-pushed the clickhouse/improve-fivetran-docs branch from 74bf704 to 659f3d2 Compare March 20, 2026 18:41

koletzilla requested a review from BentsiLeviav March 20, 2026 18:45

koletzilla marked this pull request as ready for review March 20, 2026 18:45

koletzilla requested review from a team as code owners March 20, 2026 18:45

vercel bot had a problem deploying to Preview – clickhouse-docs March 20, 2026 18:51 Failure

Fix links

dc0d5f7

vercel bot had a problem deploying to Preview – clickhouse-docs March 23, 2026 09:59 Failure

link

1142e0e

vercel bot deployed to Preview – clickhouse-docs March 23, 2026 11:03 View deployment

dhtclk requested changes Mar 23, 2026

View reviewed changes

koletzilla and others added 4 commits March 24, 2026 10:47

Update docs/integrations/data-ingestion/etl-tools/fivetran/index.md

6e08af8

Co-authored-by: Dominic Tran <dominic.tran@clickhouse.com>

Update docs/integrations/data-ingestion/etl-tools/fivetran/reference.md

8db355e

Co-authored-by: Dominic Tran <dominic.tran@clickhouse.com>

Update docs/integrations/data-ingestion/etl-tools/fivetran/index.md

5bcef42

Co-authored-by: Dominic Tran <dominic.tran@clickhouse.com>

Update docs/integrations/data-ingestion/etl-tools/fivetran/troublesho…

2ff83b8

…oting.md Co-authored-by: Dominic Tran <dominic.tran@clickhouse.com>

vercel bot deployed to Preview – clickhouse-docs March 24, 2026 10:08 View deployment

BentsiLeviav reviewed Mar 24, 2026

View reviewed changes

BentsiLeviav requested changes Mar 24, 2026

View reviewed changes

		\| LOCALDATE \| [Date](/sql-reference/data-types/date) \|
		\| LOCALDATETIME \| [DateTime](/sql-reference/data-types/datetime) \|


		The Fivetran ClickHouse destination maps [Fivetran data types](https://fivetran.com/docs/destinations#datatypes) to ClickHouse types as follows:

		\| Fivetran type \| ClickHouse type \|


		### Ensure cluster health during syncs {#cluster-health}

		The Fivetran destination checks that all replicas are active before performing operations. If any replica is offline, operations fail after retrying for up to 600 seconds.

Conversation

koletzilla commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel bot commented Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dhtclk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

koletzilla commented Mar 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BentsiLeviav left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

koletzilla commented Mar 18, 2026 •

edited

Loading

vercel bot commented Mar 18, 2026 •

edited

Loading