Warehouse properties
Contents
Warehouse properties copy columns from a synced Data Warehouse table or a materialized view onto your person properties and group properties. Each row is matched to a person or a group by a key column. The mapped columns then stay up to date on every sync.
Use it when the truth about a customer lives in another system. Plan tier, seat count, MRR, contract renewal date, and lifecycle stage usually live in Stripe, Salesforce, HubSpot, or your own Postgres, not in your product events.
Once a column is mapped, it behaves like any other person or group property. You can filter insights with it, build cohorts from it, target feature flags and experiments with it, and use it in surveys.
Warehouse properties or a join?
PostHog gives you two ways to use warehouse data about a person. They are not interchangeable.
| Warehouse properties | Person join | |
|---|---|---|
| How it works | The value is written onto the person profile | The tables are joined when a query runs |
| Where you can use it | Anywhere a person property works | Insights, filters, and breakdowns |
| Feature flags and experiments | Yes | No |
| Cost of a value | One property update per changed row | No writes |
| Freshness | Updated on each warehouse sync | Always current at query time |
Choose warehouse properties when something outside of a query has to read the value. Feature flags and experiments evaluate against stored person properties, so a join is invisible to them.
Choose a join when you only need the data in insights and SQL. A join adds no writes and never goes stale.
Before you start
You need three things:
- A linked source that syncs the table you want to read, or a materialized view.
- A column in that table or view holding each row's distinct ID, for person properties. For group properties, you need the column holding each row's group key.
- People or groups that already exist in PostHog.
The last point is the one that catches people out. A sync only updates a person who is already in PostHog. It never creates one. If your warehouse holds 50,000 customers and only 12,000 of them have used your product, the other 38,000 rows are skipped.
Group properties also need group analytics and at least one group type. The Groups tab is hidden until you have both.
Set up a warehouse property
- Go to Data > Warehouse properties.
- Select the Persons or the Groups tab.
- Click Add person property, or Add group property.
- Give the mapping a name, and a description if it helps the next person to read it.
- For groups, select the Group type it attaches to.
- Select the synced table or materialized view to read from.
- Select the Distinct ID column, or the Group key column for groups. This is how a row finds the person or group to update.
- Map each warehouse column to the property name to write it to. Add one row per column. Each mapped column takes its own optional description.
- Save.
PostHog starts a backfill as soon as you save, so the first values arrive without another sync.
You need project admin access, plus edit access on the warehouse source behind the table, or on the materialized view. Mapping a table drives its billable sync, so viewing the source is not enough.
What you can change later
The table and the column mappings are fixed once you save. To change either, delete the mapping and create it again.
The key column and the on/off toggle stay editable.
Properties that arrive this way carry a Warehouse provenance tag in property lists, so you can tell them apart from the ones your SDK sets.
Naming the property
The property name is what you see in filters, so write it the way you want to read it later. A warehouse column called sub_plan_tier can map to a property called plan.
The value itself is copied as it stands. PostHog does not convert units or reformat it, so a column holding cents arrives as cents.
You can map a synced table or a materialized view. A view or saved query that has not been materialized is not selectable. Use a materialized view to join tables or compute values before copying them to properties.
Map a column once. Two sources that write the same property name fight each other, and the last sync wins.
When your key is a person property
For person properties, the key column must contain an existing person's distinct ID. It cannot match directly on a person property such as customer_id, or on PostHog's internal person UUID (persons.id). Rows whose key does not resolve to a distinct ID are counted as Skipped (no person).
If your warehouse uses another identifier, create a materialized view that joins it to persons through the matching person property, then to person_distinct_ids through person_id. Output the resolved distinct_id as the key column.
For example, suppose warehouse_customers has one row per customer, with string columns customer_id and plan, and each matching person has the same string in properties.customer_id:
Replace the table, property, and column names with your own. Confirm that the customer IDs have the same type and format on both sides, are nonempty, and identify only the intended person. If several people share a customer ID, this join updates all of them.
Resolve duplicate warehouse rows before using the view so each person receives one set of values. The inner query uses min(distinct_id) to pick one existing distinct ID per person, avoiding duplicate updates for people with multiple IDs.
- Run the query in the SQL editor and check that each returned distinct ID belongs to the intended person.
- Save and materialize the view. Use full refresh so changes to person properties and identity mappings are picked up on the next refresh.
- Add a person property mapping, select the materialized view, and choose
distinct_idas the Distinct ID column. - Map
planto the person property you want to write. Keep thecustomer_idproperty used by the join separate from the properties this mapping writes.
The inner joins exclude customers with no matching person or distinct ID. Those rows never reach the property sync, so they do not appear in its skipped count. This does not create people or change how PostHog matches warehouse property keys.
How syncing works
A warehouse property sync runs after its table's warehouse import or its view's materialization. It does not run on its own schedule. For a synced table, every enabled mapping runs in this order:
- It reads the rows the import staged. An incremental import stages only the rows it added or changed, so a quiet table reads zero rows.
- It builds a bundle of the mapped values for each row, keyed by the distinct ID or group key.
- It compares each bundle against the values it last sent, and drops the ones that did not change.
- It drops the rows whose key matches no existing person or group.
- It sends one property update per surviving row.
Step 3 means a full refresh does not resend everything. It only sends what actually differs from the last send.
Step 4 is where rows go missing. The run history reports that count separately, under Skipped (no person).
Materialized views use the same property sync steps after refreshing. Sync now refreshes the view, and Backfill reads its stored results. Views on the older data modeling schedule do not update properties automatically; Sync now reports this limitation. Refresh the view, then use Backfill to update its properties.
A person update arrives as a $set event. A group update arrives as a $groupidentify event. PostHog sends them at a controlled rate, so a large backfill lands over time rather than all at once.
Sync now and backfill
Two buttons sit on each row of the table:
- Sync now runs the table's warehouse import, then the property sync behind it. Use it when the warehouse has new rows you want now.
- Backfill reads the whole table instead of the last import's changed rows. Use it after you add a column to a mapping, so people who have not changed since then get the new property.
Only one run happens at a time per table. Both buttons are disabled while a run is in flight.
Reading the run history
Expand a row to see its runs. The counts follow the steps above:
| Column | What it means |
|---|---|
| Status | Whether the run finished. A completed run that updated nobody is normal |
| Trigger | What started the run: the sync schedule, Sync now, or Backfill |
| Rows read | Rows the import staged for this run |
| Updated | People or groups updated, out of the rows whose values changed, with the share of those rows |
| Skipped (no person) | Changed rows whose key matched no existing person. Reads Skipped (no group) on the Groups tab |
A row of zeros is not a failure on its own. The status carries a short note that says which zero you are looking at: no new rows means the import brought nothing, and no changes means every row already holds the values last sent.
Turning a mapping off
Toggle a mapping off to stop updating its properties without deleting it. Values already synced stay on the people and groups. They stop changing.
Deleting the mapping does the same and removes the configuration. Neither action removes the property values from person profiles.
Costs
Each updated person or group sends one event, so it counts toward your event volume. The comparison in step 3 exists to keep that number down. A column that rarely changes costs almost nothing after the first sync.
A wide mapping costs more than a narrow one. One changed column resends every property the mapping covers for that person, because the comparison covers the whole bundle rather than each property on its own. Split volatile columns into their own mapping if you map a mix of stable and fast-changing data.
The warehouse sync itself is billed by rows synced. See Sources pricing.
Troubleshooting
A property never appears on anyone. Check the Skipped (no person) count in the run history. A high number means the key column does not hold the same value as the person's distinct ID. Compare a row in the warehouse table against the person in PostHog.
A property appears on some people only. The people who are missing it probably do not exist in PostHog yet, or have not changed in the warehouse since you added the mapping. Run a backfill.
Every run reads zero rows. The import itself brought nothing. Open the table's sync history in the data warehouse to see the import's own runs and errors.
A run failed. The status tag carries the error. A property sync that rode a failing import fails with it, so check the table's sync history first.
The mapping turned itself off. Five failed runs in a row disable a mapping, so a broken table does not retry forever. Fix the underlying sync, then toggle it back on. The failure count resets after a run succeeds.
Self-hosting
Self-hosted instances have this feature enabled by default. Set WAREHOUSE_PERSON_PROPERTIES_ENABLED_SELF_HOSTED to False to disable it. See environment variables for more.





