Segmenty

Segmenty jsou uložené filtry hráčů. Segment je definován jako strom trait + event podmínek; materializován jako sada player_ids v players.segment_ids[]. Campaign fan-out joinuje na GIN-indexed array — rychlé i na 1M-player tenantech.

Definition shape

{
  "operator": "AND" | "OR",
  "conditions": [
    { "type": "trait", "field": "total_deposited", "op": ">", "value": 100000 },
    { "type": "trait", "field": "kyc_status", "op": "=", "value": "verified" },
    {
      "type": "event",
      "event": "bet_settled",
      "window": { "kind": "rolling", "days": 7 },
      "aggregation": "count",
      "op": ">=",
      "value": 5
    },
    {
      "operator": "OR",
      "conditions": [
        { "type": "trait", "field": "current_tier_code", "op": "=", "value": "gold" },
        { "type": "trait", "field": "current_tier_code", "op": "=", "value": "platinum" }
      ]
    }
  ]
}

Trait podmínky se vyhodnocují proti players řádku (Postgres). Event podmínky proti raw_events v ClickHouse s rolling time window. Skupiny se mohou vnořovat — operátoři staví komplexní segmenty kombinováním AND/OR.

Povolená trait pole

external_id, email, phone, telegram_id,
status, kyc_status, kyc_level, current_tier_code,
default_currency_code, timezone,
total_deposited, total_withdrawn, total_wagered, total_won, ggr,
bet_count, session_count,
churn_score, ltv_predicted,
first_seen_at, last_seen_at, last_bet_at, last_deposit_at,
created_at,
rg_self_excluded

Plus vertical_activity.casino.bet_count a podobné pro sportsbook (čteno z JSONB).

Povolené operátory

• Equality: =, !=
• Numeric: >, >=, <, <=
• Set: in, not_in (s array hodnotou)
• String: contains, starts_with
• Existence: exists (bez hodnoty)

Refresh strategie

Strategie	Kdy se členství aktualizuje
on_demand	Pouze manuální POST /v1/segments/:id/refresh
scheduled	Cron (default denně)
realtime	Stream-processor volá /v1/internal/recompute-player-segments po každé mutaci atributu hráče; sweeper zavře gap s 30s catch-up cyklem

realtime je default pro nové segmenty. Nastavitelné přes Admin UI nebo PATCH /v1/segments/:id { refresh_strategy: "realtime" }.

Sample preview

Segment editor zobrazuje live count + 10-řádkový sample, jak budujete podmínku. Counts jsou estimace (použijte /v1/segments/:id/refresh endpoint pro získání přesných čísel + materializaci členství).

Segment templates

Built-in šablony pro běžné patterny: "high rollers", "churn risk", "first-deposit declined", "sportsbook bettors", "VIP candidates". Vyberte + tweakněte; uloží typed shape s názvem.

Performance notes

• Trait-only segmenty se kompilují do jediného Postgres WHERE fragmentu + jsou vyhodnocovány v O(rows scanned) přes indexy na players.{tenant_id, last_seen_at, kyc_status, current_tier_code, …}.
• Event-aggregation segmenty narazí na ClickHouse s tenant + time-window filtrem — columnar engine + ordering na (tenant_id, project_id, player_id, timestamp) to drží rychlé i pro 100M-event tenanty.
• Materializace členství je UPDATE players SET segment_ids = ? per dotčený řádek — touched řádky jsou typicky <1% player tabulky.