Export ClickHouse

Evenimentele de click se află în ClickHouse (tabela click_events). Astăzi le scoți printr-un export programat către stocare compatibilă S3; dashboardul oferă și exporturi CSV asincrone din Analytics.

Planificat, încă indisponibil; vezi roadmap-ul. Următoarele nu sunt implementate: un DSN ClickHouse doar-citire per workspace (/clickhouse-dsn), ieșire Parquet, destinații BigQuery și Snowflake (API-ul acceptă acele valori kind, dar worker-ul de export le respinge), gazde DSN per regiune și o tabelă conversions în ClickHouse (conversiile se află în Postgres). Secțiunile 3 și 4 de mai jos descriu ce există astăzi.

1. Ce există astăzi

Capabilitate	Stare
Export programat către S3 / MinIO (`kind: "s3"`)	Disponibil
Programe	`hourly` sau `daily` (implicit `daily`)
Format de ieșire	NDJSON comprimat gzip, un click pe linie
Export CSV asincron din dashboard	Disponibil (`/analytics-exports`)
DSN ClickHouse direct, doar-citire	Planificat
Ieșire Parquet	Planificat
Destinații BigQuery / Snowflake	Planificat

2. Schema

Click-urile brute sunt stocate în click_events:

Coloană	Tip	Note
`timestamp`	`DateTime64(3, 'UTC')`	precizie de milisecundă
`link_id`	`UInt64`	ID-ul rândului link-ului
`workspace_id`	`UInt64`
`domain_id`	`UInt64`
`slug`, `host`	`LowCardinality(String)`
`user_agent`, `referer`	`String`
`ip`	`String`	stocat integral, netrunchiat
`country_code`	`FixedString(2)`	ISO-3166-1 alpha-2
`device`, `browser`	`LowCardinality(String)`
`destination`	`String`	URL-ul destinației rezolvate
`is_suspicious`, `suspicion_reasons`	`UInt8`, `Array(String)`	indicator euristic de fraudă la click
`anonymizer_type`	`LowCardinality(String)`	clasificare VPN / proxy

Nu există click_id per click, iar UTM-urile nu sunt stocate în coloane separate; fac parte din URL-ul destinației.

Exportul programat scrie în prezent aceste câmpuri pentru fiecare click: timestamp, link_id, workspace_id, domain_id, slug, host, user_agent, referer, ip, country_code, device, browser, destination. (device, browser și destination sunt exportate momentan ca șiruri goale.)

3. Export S3 programat

Necesită permisiunea 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" }
  }'

Gestionează configurațiile cu GET /v1/workspaces/{id}/export, PATCH /v1/workspaces/{id}/export/{kind}/enabled și DELETE /v1/workspaces/{id}/export/{kind}.

Fiecare rulare scrie un obiect per workspace: <prefix>/exports/<workspace_id>/<YYYY-MM-DD>/clicks_<HHMMSS>.ndjson.gz. Prima rulare exportă tot istoricul; rulările următoare exportă doar click-urile de la rularea anterioară. Pentru cei care se găzduiesc singuri: endpoint-ul S3 și credențialele vin din mediul api-core.

4. Încărcarea într-un data warehouse

Fiindcă fișierele sunt NDJSON, BigQuery (bq load --source_format=NEWLINE_DELIMITED_JSON), Snowflake (COPY INTO cu TYPE = JSON) și Redshift le pot încărca din bucket cu loader-ele lor standard. Parquet nativ și destinații BigQuery / Snowflake de tip push sunt planificate.

5. Cazuri limită

Latență - exporturile rămân în urmă cu intervalul programului (din oră în oră = până la 60 de minute în urmă).
Retenție - în prezent nu există expirare automată (TTL) pe click_events; ferestre de retenție în funcție de plan sunt planificate.
Fixarea regiunii - încă indisponibilă; toate datele de click sunt stocate în deployment-ul din UE.
Evoluția schemei - coloanele se adaugă cu ALTER TABLE ... ADD COLUMN IF NOT EXISTS și valori implicite; coloanele existente nu se redenumesc.

Vezi și

Urmărirea conversiilor - cum sunt înregistrate conversiile (în Postgres, prin webhook-uri Stripe / Shopify)
Referința API - endpoint-uri de configurare a exportului