Skip to main content
The ClickHouse integration ingests billable events for usage metering directly from a table or view in your ClickHouse: Alguna connects nightly, reads the rows added since the last run, and turns each into a usage event with the same shape as one sent to POST /events. Use it when usage already lands in ClickHouse and you would rather not build an event pipeline. Usage sources are described together in How Alguna works; the sibling connector is BigQuery.

​
Pre-requisites

  • A ClickHouse deployment that is reachable from the public internet — ClickHouse Cloud, or a self-hosted instance with a publicly exposed endpoint. Instances that are only reachable inside a private network (VPC peering, PrivateLink, SSH tunnels) are not supported.
  • TLS is required. Alguna connects over the ClickHouse native protocol with TLS (typically port 9440). Plaintext connections are refused.
  • A database user for Alguna with SELECT permission on the source table or view.
If your ClickHouse restricts inbound traffic by IP, allowlist Alguna’s egress IPs — contact us for the current list for your environment.

​
How it works

  1. On a nightly schedule, Alguna connects to your ClickHouse and runs a SELECT over the configured table, ordered by your state field.
  2. Only rows with a state-field value strictly greater than the last successfully ingested value are fetched, so each run is incremental.
  3. Each row becomes one usage event: the configured account, event-name, and timestamp columns map to the event’s identity, and every other column is attached as an event property.
Very large backfills are automatically split across runs: a run stops at a configurable per-run row cap (always on a state-field boundary) and the next run resumes from where it left off.

​
Choosing a state field

The state field drives incremental syncing, so it must be monotone with respect to when rows become visible in your table:
If your events can arrive late — batch loads, pipeline retries, backfills that insert rows with older event timestamps — use an insert-timestamp column (for example a DEFAULT now() materialized column) as the state field, not the event timestamp. Rows whose state-field value is behind the sync cursor are never picked up.
The state field can be a Date or a DateTime/DateTime64 column; configure the matching type (DATE or TIMESTAMP).

​
Configuration

Set up the connection in the dashboard under Settings → Connections → Integrations → ClickHouse:

​
Event mapping

Only the mapped columns are treated specially — every other column in the table is ingested as an event property. If you want to project or filter what Alguna sees, point the configuration at a ClickHouse view.

​
Monitoring

The integration page shows the run history for each configuration: when each sync ran, how many events it ingested, the latest event timestamp, and whether the run was truncated by the per-run row cap.
  • Send usage events — the event shape rows are mapped onto, and the API and CSV alternatives
  • Create metrics — aggregating the ingested events
  • BigQuery — the same integration for BigQuery tables