Сегменти

Translator note: machine-translated baseline. Needs human review by a native UK speaker. EN source is canonical.

Сегменти — це збережені фільтри гравців. Сегмент визначений як дерево trait + event умов; матеріалізований як набір player_ids в players.segment_ids[]. Campaign fan-out joinить на GIN-indexed масив — швидко навіть на 1M-player tenants.

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 умови оцінюються проти players row (Postgres). Event умови — проти raw_events в ClickHouse з rolling time window. Групи можуть вкладатись — оператори будують complex сегменти комбінуванням AND/OR.

Дозволені trait fields

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

Плюс vertical_activity.casino.bet_count і подібні для sportsbook (читається з JSONB).

Дозволені оператори

• Equality: =, !=
• Numeric: >, >=, <, <=
• Set: in, not_in (з array value)
• String: contains, starts_with
• Existence: exists (без value)

Refresh strategies

Strategy	Коли membership оновлюється
on_demand	Manual POST /v1/segments/:id/refresh тільки
scheduled	Cron (default daily)
realtime	Stream-processor викликає /v1/internal/recompute-player-segments після кожної мутації атрибута гравця; sweeper закриває gap з 30s catch-up циклом

realtime — default для нових сегментів. Set через Admin UI або PATCH /v1/segments/:id { refresh_strategy: "realtime" }.

Sample preview

Segment editor показує live count + 10-row sample поки ви будуєте умову. Counts — estimates (використайте /v1/segments/:id/refresh endpoint для отримання точних чисел + matterialise membership).

Segment templates

Built-in templates для common patterns: "high rollers", "churn risk", "first-deposit declined", "sportsbook bettors", "VIP candidates". Виберіть + tweak; зберігає typed shape з ім'ям.

Performance notes

• Trait-only сегменти компілюються в єдиний Postgres WHERE fragment + оцінюються в O(rows scanned) через indexes на players.{tenant_id, last_seen_at, kyc_status, current_tier_code, …}.
• Event-aggregation сегменти hit ClickHouse з tenant + time-window filter — columnar engine + ordering on (tenant_id, project_id, player_id, timestamp) тримає це швидко навіть для 100M-event tenants.
• Membership materialisation — це UPDATE players SET segment_ids = ? per affected row — touched rows зазвичай <1% player table.