Configuration des propriétés warehouse

Les propriétés warehouse écrivent des colonnes d'une table warehouse ou d'une vue matérialisée sur les personnes ou groupes correspondants, selon le calendrier de synchronisation de cette table. Elles remplacent un cron qui envoie des événements identify $set.

La mise en correspondance est tout le travail. La plupart des tables à mapper sont larges, donc le travail consiste à décider quelles colonnes deviennent des propriétés et comment elles s'appellent — non à faire beaucoup d'appels API. Une seule source porte toute la mise en correspondance : custom-property-sources-create prend le column_property_map complet en une seule requête, donc ne bouclez jamais par colonne.

Quand utiliser cette compétence

• « Synchroniser mes colonnes postgres.customer_attributes vers des propriétés person »
• « Nous envoyons un job identify quotidien depuis notre warehouse, PostHog peut-il le récupérer à la place ? »
• « Mapper cette table à des people » / « reverse ETL dans PostHog »
• L'utilisateur regarde Data → Warehouse properties et veut une table entière mappée

Utilisez setting-up-a-data-warehouse-source à la place quand la table n'est pas encore dans le warehouse. Cette compétence démarre une fois que les données se synchronisent.

Outils

Les cibles person et group ont besoin de la feature warehouse-person-properties. Une cible group a en plus besoin du scope group:write ; sans lui, custom-property-sources-create refuse la définition de groupe.

Le flux

1. Trouver la table et ses colonnes

Pour une table synchronisée, external-data-schemas-list vous donne le schema id (le binding external_data_schema), et external-data-schemas-retrieve retourne les colonnes et types de ce schema.

Pour une vue matérialisée, view-list trouve la vue et son schema de colonnes, et view-get retourne les colonnes d'une vue par id ; une vue se lie par saved_query à la place, et doit déjà être matérialisée, puisqu'une vue non matérialisée n'a pas de données à lire et l'appel create la rejette.

2. Choisir la colonne d'identifiant, et expliquer pourquoi c'est important

Demandez quelle colonne contient le distinct ID PostHog (cibles person) ou la clé de groupe (cibles group). C'est la raison la plus courante pour laquelle une mise en correspondance ne fait rien silencieusement, donc ne le devinez pas à partir d'un nom comme id ou user_id sans confirmation.

Deux propriétés de la synchronisation valent la peine d'être énoncées clairement avant l'engagement de l'utilisateur :

• Elle ne met à jour que les personnes ou groupes qui existent déjà dans PostHog. Les lignes qui ne correspondent à personne sont ignorées, et l'exécution les rapporte comme skipped_missing_person. Elle ne crée pas de personnes.
• Les valeurs null sont ignorées, pas écrites. Une colonne null pour une ligne laisse cette propriété comme elle était. Si l'utilisateur s'attend à ce qu'un null efface une propriété, les propriétés warehouse ne le feront pas.

3. Proposer la mise en correspondance avant de créer quoi que ce soit

Construisez le column_property_map complet — {warehouse_column: property_name} — et montrez-le à l'utilisateur pour approbation. Par défaut à le même nom des deux côtés ; un renommage est la décision de l'utilisateur, pas une conjecture qui vaut la peine.

Exclure de la proposition, et dire ce que vous avez exclu :

• La colonne d'identifiant. Ses valeurs identifient la personne, elles ne la décrivent pas.
• Tout ce qui est préfixé par $, et email, name, username. Ce sont des propriétés d'identité que les SDKs définissent, et les écrire depuis le warehouse peuvent écraser ce que PostHog connaît déjà.
• Colonnes qui seraient sensibles comme propriété person. Hashs de mots de passe, tokens, colonnes d'audit internes, et tout ce que l'utilisateur ne voudrait pas voir dans l'interface UI du profil person. Signalez-les plutôt que de les supprimer silencieusement, puisque seul l'utilisateur connaît son schema.

Puis vérifier les collisions : lire les propriétés person existantes et pointer tout nom mappé qui existe déjà, car la synchronisation l'écrasera à chaque exécution. custom-property-definitions-list affiche les propriétés warehouse déjà configurées, vous pouvez donc aussi repérer une table qui est déjà mappée.

Les tables larges sont exactement quand c'est important — une table de vingt colonnes proposée comme liste brute n'est pas examinable. Grouper la proposition en ce qui sera mappé, ce que vous avez exclu et pourquoi, et ce qui entre en collision.

4. Le créer

Créer d'abord la définition, puis la source :

1. custom-property-definitions-create avec target_type: person (ou group plus group_type_index), display_type: text, et un nom décrivant le groupe de propriétés, pas une colonne — la définition est la ligne que l'utilisateur voit dans l'interface UI. display_type est requis par l'API ; utilisez text pour les cibles person et group, où il est ignoré (il ne pilote que la façon dont une propriété de compte s'affiche, puisque les propriétés de profil s'écrivent comme des valeurs brutes $set / $group_set).
2. custom-property-sources-create avec l'id de définition, exactement l'un de external_data_schema ou saved_query, tout le column_property_map, et key_column défini à l'identifiant de l'étape 2.

La mise en correspondance et la liaison sont create-only. Pour changer quelles colonnes sont mappées, supprimer la propriété et la créer à nouveau — donc ça vaut la peine d'obtenir la proposition juste plutôt que d'itérer sur une mise en correspondance en direct.

5. Backfill et vérifier

Créer une source activée démarre automatiquement un backfill. Pour une mise en correspondance existante, custom-property-sources-backfill lit la table entière et remplit les lignes historiques ; elle coalesce si une est déjà en cours d'exécution.

Puis lire custom-property-sources-runs-list et parcourir l'entonnoir, c'est là qu'une mise en correspondance qui « n'a rien fait » s'explique :

Une exécution qui lit des lignes mais affiche existing: 0 est le cas de mauvaise-colonne-clé presque à chaque fois.

Notes qui économisent un aller-retour

• La synchronisation suit le propre calendrier de la table. Il n'est pas séparément planifiable, donc « à quelle fréquence ceci se met-il à jour » est répondu par la fréquence de synchronisation de la table.
• Une source qui échoue à répétition est désactivée automatiquement après cinq défaillances consécutives. La réactiver réinitialise la série et déclenche un backfill frais.
• « Synchroniser maintenant » exécute la table sous-jacente, qui pour une table synchronisée est une vrai synchronisation warehouse facturable, et pour une vue matérialisée est une matérialisation. Ce n'est pas un no-op bon marché — ne l'appelez pas pour « vérifier » une mise en correspondance quand custom-property-sources-runs-list répond à la question gratuitement.