Skippr Docs

Appearance

How ClickHouse Defines the Raw Data Contract ​

July 2026

For ClickHouse, raw data means the rows your chosen tables return over HTTP, or the explicit output of one query if you use query instead of tables.

Short Answer ​

The raw data contract for ClickHouse is the exact rowset returned from the tables you name in the selected database, or the exact output of the custom SQL query if you use query instead of tables. Skippr reads through the ClickHouse HTTP API, so the raw layer is whatever that endpoint returns for the objects you explicitly selected.

That means the contract is straightforward to explain. If the source config points at default.events, raw data is the rows in default.events, namespaced as clickhouse.default.events. If the config switches to a query that selects user_id, event_name, and occurred_at, the contract is now that projected row shape and not the full underlying table.

Why Teams Struggle with This ​

Teams usually get confused when they treat ClickHouse as if it were a low-level replication feed. The source connector is much simpler than that: it exposes a readable table or query boundary, and the raw contract only stays stable if that boundary stays explicit.

  • The chosen database and tables list define the contract more than the connector name does.
  • A custom query overrides tables, so a column alias or filter in that query becomes part of the promised raw shape.
  • Read access to the selected database and tables is required before the row contract matters at all.
  • If the team really needs change events or transaction ordering, ClickHouse table extraction is the wrong raw-data story to tell.

How Skippr Handles It ​

Skippr keeps the boundary visible in config: url, database, user, and either tables or query. That is useful because another engineer can review the source and see whether Skippr is reading a durable table contract or a one-off SQL projection.

The namespace pattern also helps explain lineage. A downstream raw table that came from clickhouse.default.metrics is easy to trace back to the exact ClickHouse database and table that produced it.

  • Reads ClickHouse over the documented HTTP interface.
  • Supports selected tables or one custom SQL query.
  • Uses the visible namespace clickhouse.{database}.{table} for table-based reads.
  • Keeps the password separate from the raw-data definition through environment interpolation.

What the First Useful Version Looks Like ​

The first useful version is one database, one table such as events, and one quick validation that the returned columns already look like the bronze table you want. That makes the contract concrete before you widen the source.

If the real contract is a query, document the projected columns and filters early. A query-defined raw layer can work well, but only if everyone understands that the query output, not the base table, is the thing Skippr is promising downstream.