> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse

Alguna supports the automatic ingestion of billable events directly from a ClickHouse table. Point Alguna at the table (or view) that holds your usage events and they are pulled in on a nightly schedule, ready for metering and billing.

## 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:

<Warning>
  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.
</Warning>

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` → `Integrations` → `ClickHouse`:

| Field               | Description                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------- |
| Host / Port         | Your ClickHouse endpoint, e.g. `abc123.eu-west-2.aws.clickhouse.cloud:9440`                     |
| Database / Table    | The database and table (or view) that holds your usage events                                   |
| Username / Password | The database user created for Alguna. The password is stored encrypted and is never shown again |
| State field         | The column used for incremental syncing (see above), and its type (`DATE` or `TIMESTAMP`)       |

### Event mapping

| Field                       | Description                                                                     |
| --------------------------- | ------------------------------------------------------------------------------- |
| Account column              | Column holding the customer account ID or alias                                 |
| Event name column           | Column holding the event name                                                   |
| Timestamp column            | Column holding the event timestamp                                              |
| Unique ID column (optional) | Column holding a unique event ID, used for deduplication. Strongly recommended  |
| Property prefix (optional)  | Prefix stripped from remaining column names before they become event properties |

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.