ClickHouse-export

Klikgebeurtenissen staan in ClickHouse (tabel click_events). Vandaag haal je ze eruit met een geplande export naar S3-compatibele opslag; het dashboard biedt ook asynchrone CSV-exports vanuit Analytics.

Gepland, nog niet beschikbaar; zie roadmap. Het volgende is niet geïmplementeerd: een alleen-lezen ClickHouse-DSN per workspace (/clickhouse-dsn), Parquet-uitvoer, BigQuery- en Snowflake- bestemmingen (de API accepteert die kind-waarden, maar de export- worker weigert ze), DSN-hosts per regio en een conversions- tabel in ClickHouse (conversies staan in Postgres). Sectie 3 en 4 hieronder beschrijven wat er vandaag bestaat.

1. Wat er vandaag bestaat

Mogelijkheid	Status
Geplande export naar S3 / MinIO (`kind: "s3"`)	Beschikbaar
Schema’s	`hourly` of `daily` (standaard `daily`)
Uitvoerformaat	met gzip gecomprimeerde NDJSON, een klik per regel
Asynchrone CSV-export vanuit het dashboard	Beschikbaar (`/analytics-exports`)
Directe alleen-lezen ClickHouse-DSN	Gepland
Parquet-uitvoer	Gepland
BigQuery- / Snowflake-bestemmingen	Gepland

2. Schema

Ruwe klikken worden opgeslagen in click_events:

Kolom	Type	Opmerkingen
`timestamp`	`DateTime64(3, 'UTC')`	precisie in milliseconden
`link_id`	`UInt64`	rij-ID van de link
`workspace_id`	`UInt64`
`domain_id`	`UInt64`
`slug`, `host`	`LowCardinality(String)`
`user_agent`, `referer`	`String`
`ip`	`String`	volledig opgeslagen, niet afgekapt
`country_code`	`FixedString(2)`	ISO-3166-1 alpha-2
`device`, `browser`	`LowCardinality(String)`
`destination`	`String`	opgeloste bestemmings-URL
`is_suspicious`, `suspicion_reasons`	`UInt8`, `Array(String)`	vlag van de heuristiek voor klikfraude
`anonymizer_type`	`LowCardinality(String)`	VPN- / proxyclassificatie

Er is geen click_id per klik en UTM’s worden niet als aparte kolommen opgeslagen; ze maken deel uit van de bestemmings-URL.

De geplande export schrijft momenteel deze velden per klik: timestamp, link_id, workspace_id, domain_id, slug, host, user_agent, referer, ip, country_code, device, browser, destination. (device, browser en destination worden op dit moment als lege strings geëxporteerd.)

3. Geplande S3-export

Vereist de machtiging export.manage.


curl -X PUT \
  https://api.elido.app/v1/workspaces/1/export \
  -H "Authorization: Bearer $ELIDO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "s3",
    "enabled": true,
    "schedule": "hourly",
    "destination": { "bucket": "acme-bi-warehouse", "prefix": "elido" }
  }'

Beheer configuraties met GET /v1/workspaces/{id}/export, PATCH /v1/workspaces/{id}/export/{kind}/enabled en DELETE /v1/workspaces/{id}/export/{kind}.

Elke run schrijft een object per workspace: <prefix>/exports/<workspace_id>/<YYYY-MM-DD>/clicks_<HHMMSS>.ndjson.gz. De eerste run exporteert alle historie; latere runs exporteren alleen klikken sinds de vorige run. Zelfhosters: het S3-endpoint en de inloggegevens komen uit de omgeving van api-core.

4. Laden in een datawarehouse

Omdat de bestanden NDJSON zijn, kunnen BigQuery (bq load --source_format=NEWLINE_DELIMITED_JSON), Snowflake (COPY INTO met TYPE = JSON) en Redshift ze met hun standaardloaders uit de bucket laden. Native Parquet en BigQuery- / Snowflake-bestemmingen in push-stijl zijn gepland.

5. Randgevallen

Latentie - exports lopen achter met het schema-interval (elk uur = tot 60 minuten achter).
Retentie - er is momenteel geen automatische verloop (TTL) op click_events; bewaartermijnen per plan zijn gepland.
Regio vastpinnen - nog niet beschikbaar; alle klikgegevens worden opgeslagen in de EU-deployment.
Schema-evolutie - kolommen worden toegevoegd met ALTER TABLE ... ADD COLUMN IF NOT EXISTS en standaardwaarden; bestaande kolommen worden niet hernoemd.

Zie ook

Conversietracking - hoe conversies worden vastgelegd (in Postgres, via Stripe- / Shopify-webhooks)
API-referentie - endpoints voor exportconfiguratie