setting-up-warehouse-properties

For a synced table, external-data-schemas-list gives you the schema id (the external_data_schema binding), and external-data-schemas-retrieve returns that schema's columns and types.

For a materialized view, view-list finds the view and its column schema, and view-get returns one view's columns by id; a view binds by saved_query instead, and must already be materialized, since an unmaterialized view has no data to read and the create call rejects it.

Ask which column holds the PostHog distinct ID (person targets) or the group key (group targets). This is the single most common reason a mapping silently does nothing, so do not guess it from a name like id or user_id without confirming.

Two properties of the sync are worth stating plainly before the user commits:

• It only updates people or groups that already exist in PostHog. Rows that match nobody are skipped, and the run reports them as skipped_missing_person. It does not create people.
• Null values are skipped, not written. A column that is null for a row leaves that property as it was. If the user expects a null to clear a property, warehouse properties will not do it.

Build the full column_property_map — {warehouse_column: property_name} — and show it to the user for approval. Default to the same name on both sides; a rename is the user's call, not a guess worth making.

Exclude from the proposal, and say what you excluded:

• The identifier column. Its values identify the person, they do not describe them.
• Anything $-prefixed, and email, name, username. These are identity properties the SDKs set, and writing them from the warehouse can overwrite what PostHog already knows.
• Columns that would be sensitive as a person property. Password hashes, tokens, internal audit columns, and anything the user would not want visible in the person profile UI. Flag them rather than dropping them silently, since only the user knows their schema.

Then check collisions: read the existing person properties and call out any mapped name that already exists, because the sync will overwrite it on every run. custom-property-definitions-list shows the warehouse properties already configured, so you can also spot a table that is already mapped.

Wide tables are exactly when this matters — a twenty-column table proposed as a bare list is not reviewable. Group the proposal into what will be mapped, what you excluded and why, and what collides.

Create the definition first, then the source:

1. custom-property-definitions-create with target_type: person (or group plus group_type_index), display_type: text, and a name describing the group of properties, not one column — the definition is the row the user sees in the UI. display_type is required by the API; use text for person and group targets, where it is ignored (it only drives how an account property renders, since profile properties are written as raw $set / $group_set values).
2. custom-property-sources-create with the definition id, exactly one of external_data_schema or saved_query, the whole column_property_map, and key_column set to the identifier from step 2.

The mapping and the binding are create-only. To change which columns are mapped, delete the property and create it again — so it is worth getting the proposal right rather than iterating on a live mapping.

Creating an enabled source starts a backfill automatically. For an existing mapping, custom-property-sources-backfill reads the whole table and populates historical rows; it coalesces if one is already running.

Then read custom-property-sources-runs-list and walk the funnel, which is where a mapping that "did nothing" explains itself:

A run that reads rows but shows existing: 0 is the wrong-key-column case almost every time.