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

# Migration Guide

> Move your queries from the legacy Data Warehouse (client_analytics) to the Analytics Warehouse.

# Migrating from the legacy Data Warehouse

The legacy warehouse (`client_analytics`) is **deprecated**. It keeps working, untouched, during the migration period — you migrate at your own pace by updating two things in your queries: the **database name** and, where they changed, **table and column names**. Your credentials and connection host may also change; your Account Manager will confirm.

<Warning>
  The legacy `client_analytics` database will be decommissioned after the migration period. All new integrations should be built against `treble_client_analytics` only.
</Warning>

## Table mapping

| Legacy (`client_analytics`)                             | New (`treble_client_analytics`)                            | Notes                                                                                            |
| ------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `fact_sessions`                                         | `fact_treble_sessions`                                     | Adds `trigger_keyword`, `last_node_id`; `inbound_outbound` → `direction`                         |
| `fact_inbound_messages`                                 | `fact_treble_sessions` filtered by `direction = 'INBOUND'` | Absorbed — same data, one table                                                                  |
| `fact_deployment_status`                                | `fact_campaign_sends`                                      | `timestamps_eta` → `scheduled_at`; `timestamp_*` → `*_at`                                        |
| `fact_deployment_daily`                                 | `fact_campaign_daily`                                      | Same formulas, same columns                                                                      |
| `fact_conversations`                                    | `fact_agent_conversations`                                 | Full history (legacy kept a rolling 3 months); adds transfer\_count, assignment fields, and more |
| `fact_agent_messages`                                   | `fact_agent_conversation_messages`                         |                                                                                                  |
| `fact_redirections`                                     | `fact_agent_conversation_transfers`                        |                                                                                                  |
| `fact_agent_status_changes`                             | `fact_agent_status_changes`                                | Same name                                                                                        |
| `fact_agent_daily`                                      | `fact_agent_daily`                                         | Same name, same formulas                                                                         |
| `fact_hsm_responses`                                    | `fact_hsm_responses`                                       | Same name                                                                                        |
| `fact_target_events`                                    | `fact_target_events`                                       | Same name                                                                                        |
| `fact_whatsapp_links`                                   | `fact_whatsapp_link_events`                                |                                                                                                  |
| `dim_agents`, `dim_tags`, `dim_teams`, `dim_agent_tags` | Same names                                                 |                                                                                                  |
| `dim_hsm`                                               | `dim_hsms`                                                 | Pluralized                                                                                       |
| `session_variables`                                     | `fact_treble_session_variables`                            | Now generally available                                                                          |
| —                                                       | `fact_treble_session_messages`                             | **New** — full conversation trace                                                                |
| —                                                       | `fact_treble_session_nodes`                                | **New** — node-by-node journey                                                                   |
| —                                                       | `fact_ad_sessions`                                         | **New** — Click-to-WhatsApp attribution                                                          |
| —                                                       | `dim_polls`, `dim_channels`, `dim_poll_nodes`              | **New** dimensions                                                                               |

## Column renames to watch for

| Legacy                                                         | New                                                            | Where                                                                 |
| -------------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
| `inbound_outbound`                                             | `direction`                                                    | sessions                                                              |
| `campaign_name`                                                | `poll_name`                                                    | agent conversations (`poll_name` is the one name used everywhere now) |
| `timestamps_eta`                                               | `scheduled_at`                                                 | campaign sends                                                        |
| `timestamp_delivered` / `_responded` / `_failure` / `_success` | `delivered_at` / `responded_at` / `failed_at` / `succeeded_at` | campaign sends                                                        |
| `answer_id`                                                    | `answer_option_id`                                             | flow nodes (it identifies the chosen option)                          |

## Behavior differences you should know

1. **Full history.** The legacy warehouse trimmed most tables to a rolling 3 months. The new warehouse serves everything. If your queries relied on the window as an implicit filter, add explicit date filters (also good for performance).
2. **Fresher "today", stated consolidation.** Data lands in minutes instead of hours, and figures for a day consolidate fully within 48 hours (see [the data contract](/en/docs/data-warehouse-v2/welcome#the-data-contract)). During a migration comparison you may see the new warehouse slightly *ahead* of the legacy on the most recent day — that is legacy refresh lag, not a discrepancy.
3. **Messages of deleted conversations are excluded** from `fact_agent_conversation_messages` by design (the conversation they belong to no longer exists).
4. **Contact enrichment on old conversations freezes.** `helpdesk_contact_id` and `contact_wa_id` on agent conversations older than 90 days keep the value they had — CRM changes no longer propagate backwards to them.
5. **Two documented formula refinements** in `fact_agent_daily`: first-response time now comes from the platform's own computation, and CSAT averages consider only conversations with a rating (`rating != 0`). Both are corrections; historical parity was verified before release.
6. **No aliases.** Legacy names are not mirrored in the new database — the mapping above is applied once, in your queries, and both systems coexist while you do it.

## Suggested migration path

1. Point a copy of your dashboard/report at `treble_client_analytics` using the mapping above.
2. Run both versions side by side for a few days; expect exact matches on consolidated days.
3. Switch over, keeping explicit date filters.
4. Tell your Account Manager when you no longer use `client_analytics` — it helps us schedule the decommission.