Improving docs around Historic People and Group property values

pages/docs/data-structure/user-profiles.mdx

@@ -151,21 +151,33 @@ You'll have the opportunity to look through all columns in the CSV to preview th
 
 ![/Screen_Shot_2021-12-01_at_12.24.00_PM.png](/Screen_Shot_2021-12-01_at_12.24.00_PM.png)
 
-## Importing Historical Profile Values 
-Historical profiles layer on additional capabilities by capturing changes in each property over time instead of just the latest value.
+## Historical Profile Values 
+Historic updates for profile property values layer on additional capabilities by capturing changes in each property over time instead of just the latest value. At this time, this functionality is dependent on our warehouse connectors feature. You can read more on how to import this type of data [here](../tracking-methods/warehouse-connectors#profile-history-tables).
 
-See here for more on how to [import](https://docs.mixpanel.com/docs/tracking-methods/warehouse-connectors#user-profiles) historical properties via Warehouse connectors.
-
-Historical properties can be used anywhere that regular profile properties can be used.
-
-For eg, when you apply breakdown by historical plan-type property, the property value will be picked based on the time of the event, instead of the current property value.
+Historical properties can be used anywhere that regular profile properties can be used. For eg, when you apply breakdown by historical plan-type property, the property value will be picked based on the time of the event, instead of the current property value.
 
 ![image](/historical_property_value.webp)
 
 When you hover over a historical property, the context menu that pops up will show that the property was sourced from a history table, as well as the name of the source. This means that the value of the property used in charts can vary over time.
 
 ![image](/dropdown_historical_property.webp)
 
+### Historic Profile Data Modeling
+
+When the data is imported from the warehouse, aside from having it available in dropdowns for query, you can see the raw data in two (2) separate areas.
+
+**Hidden event**: under the hood, the data is modeled through events, linked in a special way, and attribution is used to obtain the value the profile had at a certain point in time. The name of the event takes after the name of the table/view we read from in the warehouse connector, so if the table name is `company_plan_history`, the event will be named `company_plan_history` too (by default it's hidden). 
+
+![image](/historic_profile_property_source.png)
+
+The event time follows the start time entries in the table, so if you have an entry for say January 1st, there will also be this event with that same time in the project. This is used for attribution. Say you have 2 entries in the table for plan values, January 1st with a value of "plan1" and an entry on June 1st with a value of "plan" 2. If you were to create a report for this user based on the historic property, any event between Jan 1st and Jun 1st would have the "plan1" value, and any event after Jun 1 would have "plan2".
+
+**Profile View**: if you navigate to the profile view of a specific user (or group) that has historic profile data, you will see the property to the left of the screen and, when you hover, you'll see a button to view the changes over time. Once clicked, you will be shown a list of the values the property has had through time.
+
+![image](/historic_profile_property_profile_view.png)
+
+For billing details, read the warehouse connectors [billing FAQ section on People/Group updates](../tracking-methods/warehouse-connectors#what-actions-impact-billing-for-warehouse-connectors).
+
 ## Deleting Profiles
 
 User Profiles can be deleted either via the [Users](https://mixpanel.com/report/users) page or programmatically via our [Engage API](https://developer.mixpanel.com/reference/delete-profile). We also provide a `people_delete` method in the mixpanel-utils library [here](https://github.com/mixpanel/mixpanel-utils#people-delete).
@@ -226,3 +238,6 @@ To delete profiles yourself, please use this [guide](https://developer.mixpanel.
 
 ### What is the frequency of updates that are supported?
 The feature supports updates at the rate of about one change per day for each user. It is meant to cover use-cases like plan type changes, MRR etc which are slowly changing dimensions. It is not intended for more frequent changes like game score updates.
+
+## How are historic profile properties calculated within custom properties?
+You can use historic user and group properties within custom properties; when used in a custom property, the value used will always be based on the time of the event.

pages/docs/tracking-methods/warehouse-connectors.mdx

@@ -301,10 +301,19 @@ Here’s an example table that illustrates what can be loaded as user profiles i
 | 12345 | [email protected] | Grace Hopper | Pro |
 | 45678 | [email protected] | Bob Noyce | Free |
 
-While Profiles typically only store the state of a user *as of now*, Profile History enables storing the state of a user *over time*. 
+While Profiles typically only store the state of a user *as of now*, Profile History enables storing the state of a user *over time*. The distinction between the value a property of the profile has now vs the value it had at the time of an event allows you to do very powerful analysis.
 
-#### Setup 
-When creating a User Profile sync, set the Table Type to “History Table”. We expect tables to be modeled as an SCD (Slowly Changing Dimensions) Type 2 table. You will need to supply a Start Time column in the sync configuration. Mixpanel will infer a row's end time if a new row with a more recent start time for the same user is detected. 
+#### Profile History tables
+To create an import of regular user profiles, pick the “Standard” Type when creating a user table import.
+
+<img src="/dw_standard_user_table.png" alt="Standard user table" width="300"/>
+
+When creating a User Profile (or Group Profile) sync, set the Table Type to “History Table”. We expect tables to be modeled as an SCD (Slowly Changing Dimensions) Type 2 table. You will need to supply a Start Time column in the sync configuration. Mixpanel will infer a row's end time if a new row with a more recent start time for the same user is detected. 
+
+<img src="/dw_historic_user_table.png" alt="Historic user property table" width="450"/>
+
+Preview from a sample profile history value table
+<img src="/dwc_profile_history_table.png" alt="Profile History table sample" width="600"/>
 
 Source table requirements: 
 - The source table for user/group history is expected to be modeled as an SCD (Slowly Changing Dimension) Type 2 table. This means that the table must maintain all the history over time that you want to use for analysis.
@@ -668,6 +677,11 @@ Automatic flattening is only available for GA4 tables. For other tables, you’l
 Consider breaking the data into smaller chunks if you’re working with large datasets. You can do this by creating views in BigQuery that only include the data you want to import — for example, limiting it to the past 6 months or 1 year.
 Note: The 20-hour query limit is a Mixpanel restriction, not a BigQuery one, to help keep the system stable for all users.
 
+### Why is mirror mode required for profile history syncs?
+Mirror mode allows Mixpanel to detect changes in your data warehouse and update historical profile data in Mixpanel accordingly. This is essential for maintaining accurate history of user profiles. When you use the Mirror mode, Mixpanel data automatically syncs with your warehouse by accurately reflecting all changes, including additions, updates, or deletions. You can learn more about the Mirror mode and its benefits in this [blog post](https://mixpanel.com/blog/mirror-product-analytics-data-warehouse-sync/)
+
+### Why am I seeing events in my project with the name of my profile table?
+Events with the same name as the table/view used for historical profile imports are auto-generated by the WH import process. These are hidden by default and are not meant to be queried directly. Billing for historical imports is done using mirror pricing (link to question below).
 
 ## Billing FAQ
 
@@ -720,6 +734,15 @@ If instead your workflow updates existing tables—by appending, updating, or de
 
 You can monitor these different operations in your billing page, where they'll appear as separate line items: Events - Updates, Events - Deletes, User - Updates, and User - Deletes.
 
+**Billing for historical table imports:**
+
+Historical tables can be imported only in mirror mode. Mirror-mode pricing updates apply to all rows imported for profile history tables.This means:
+- Historical profile updates DO count towards billing. Imports through standard profile tables do not.
+- Every row counts as a mirror event and is [billed as such](../pricing#i-am-using-the-warehouse-add-on-for-ingesting-data-how-does-this-impact-billing).
+- If you update/delete existing rows in your table, [mirror billing](../pricing#i-am-using-the-warehouse-add-on-for-ingesting-data-how-does-this-impact-billing) will be applied including for backfills.
+
+For MTU plans, the events and updates/deletes don't directly affect the MTU tally unless the volume of events and updates pushes the threshold for the guardrail (by default 1000 events per user); once the threshold for the guardrail is crossed, events and updates from profile history tables will also count towards billing.
+
 ### When should I use Mirror vs. Append mode?
 
 **Use Mirror mode when:**