ClickHouse source

​

Required access

CREATE USER arcyria_reader
  IDENTIFIED BY 'replace-with-a-secret';

GRANT SELECT ON analytics.* TO arcyria_reader;

​

Connection fields

​

Create the connection

1. Open Connections.
2. Click + New Connection.
3. Set the role to Source.
4. Choose ClickHouse.
5. Fill the connection fields.
6. Click Test Connection.
7. Save only after the test succeeds.

​

Discover and preview

1. Open the pipeline Source tab.
2. Click Discover catalog.
3. Enable each required database.table stream.
4. Choose its sync mode and cursor when applicable.
5. Preview representative rows and confirm field types.
6. Click Save stream settings.

​

Full Table mode

​

Incremental mode

• updated_at for inserts and updates;
• created_at for append-only tables; or
• a monotonically increasing identifier.

CREATE INDEX IF NOT EXISTS events_updated_at_idx
  ON events (updated_at)
  TYPE set(0) GRANULARITY 1;

​

Type compatibility

• UInt*, Int*, Float*, Decimal
• String, FixedString, LowCardinality(...)
• Date, Date32, DateTime, DateTime64
• UUID, IPv4, IPv6
• Enum8, Enum16
• Nullable(...), Array(...), Map(...), Tuple(...)

• DateTime64 values with more than microsecond precision are read to microseconds.
• Integers wider than 128 bits and decimals wider than 38 digits are kept exactly as text.

​

Table engines

• Queue tables (Kafka, RabbitMQ, NATS, FileLog, S3Queue, AzureQueue) are never read, because reading them would consume messages. They appear in discovery as not readable. Read the table a materialized view writes to instead.
• Null tables always read zero rows. Distributed, Merge, Dictionary, and tables that read external storage are readable; their cost and contents follow the cluster or the external system.
• ReplacingMergeTree and other merge engines can return more than one row per key until ClickHouse merges them. Turn on Read with FINAL in the stream’s incremental settings to read one row per key; reads are slower.

​

Sample source table

CREATE TABLE events (
  event_id UInt64,
  event_time DateTime64(3, 'UTC'),
  user_id UInt64,
  amount Decimal(18, 4),
  status Enum8('new' = 1, 'done' = 2, 'failed' = 3)
) ENGINE = MergeTree
ORDER BY (event_time, event_id);

​

Troubleshooting

• Connection refused: verify host, HTTP port, network allowlist, and firewall rules.
• Authentication failed: verify username, password, and database name.
• TLS connection failure: check the Secure / TLS toggle and the HTTP port. For self-hosted ClickHouse on TLS, make sure the certificate is publicly trusted or supply the CA certificate.
• No tables discovered: grant SELECT on the schema and tables. System schemas are filtered out by design.
• Preview fails: check table permissions and unsupported custom types.
• Incremental rows missing: confirm the cursor changes on updates and is not null. Updates made with ALTER UPDATE and deleted rows are not seen by a cursor unless your writes also change the cursor column.
• A table cannot be read: it uses a queue or streaming engine; see Table engines.
• Duplicate destination rows: use a stable primary key and Upsert delivery.