setting-up-warehouse-properties

ウェアハウスプロパティの設定

ウェアハウスプロパティは、ウェアハウステーブルまたはマテリアライズドビューの列を、一致する人物またはグループに、テーブルの同期スケジュールに合わせて書き込みます。$set identify イベントを送信する cron の代わりになります。

マッピングが作業のすべてです。マッピングする価値のあるテーブルの多くは列数が多いため、どの列をプロパティにするか、またその名前をどうするかを決めることが作業の中心です。API 呼び出しをたくさん行うわけではありません。マッピング全体を 1 つのソースに設定します。custom-property-sources-create は、完全な column_property_map を 1 回のリクエストで受け取るため、列ごとにループしてはいけません。

このスキルを使うタイミング

• 「postgres.customer_attributes の列を人物プロパティに同期したい」
• 「ウェアハウスから毎日 identify ジョブを送信していますが、代わりに PostHog が取得できますか？」
• 「このテーブルを人物にマッピングしたい」／「PostHog にリバース ETL したい」
• ユーザーが Data → Warehouse properties を表示していて、テーブル全体をマッピングしたい

テーブルがまだウェアハウスにない場合は、代わりに setting-up-a-data-warehouse-source を使用してください。このスキルは、データの同期が始まった後に使用します。

ツール

ツール	目的
external-data-schemas-list	同期済みテーブルとそのスキーマ ID（external_data_schema バインディング）を探します。列はここでは省略されます
external-data-schemas-retrieve	スキーマ ID を指定して、同期済みテーブルの列と型を読み取ります
view-list	マテリアライズドビューとその列スキーマ（saved_query バインディング）を探します
view-get	ID を指定して、マテリアライズドビューの列と型を読み取ります
custom-property-definitions-list	チームにすでに存在するウェアハウスプロパティを確認します
custom-property-definitions-create	ソースが紐付ける定義を作成します（target_type: person または group）
custom-property-sources-create	定義をテーブルに紐付け、完全な column_property_map を設定します
custom-property-sources-backfill	マッピングの作成後、過去の行を取り込みます
custom-property-sources-runs-list	同期またはバックフィル後に実行状況を確認します
custom-property-sources-sync	基盤となるテーブルを今すぐ実行します

人物およびグループのターゲットには、warehouse-person-properties 機能が必要です。グループをターゲットにするには、さらに group:write スコープも必要です。このスコープがない場合、custom-property-sources-create はグループ定義を拒否します。

手順

1. テーブルとその列を探す

同期済みテーブルの場合、external-data-schemas-list でスキーマ ID（external_data_schema バインディング）を取得し、external-data-schemas-retrieve でそのスキーマの列と型を取得できます。

マテリアライズドビューの場合、view-list でビューとその列スキーマを探し、view-get で ID を指定してビューの列を取得できます。ビューは代わりに saved_query で紐付けます。また、マテリアライズドビューになっている必要があります。マテリアライズされていないビューには読み取るデータがなく、作成リクエストが拒否されるためです。

2. 識別子の列を選び、それが重要な理由を伝える

どの列に PostHog のdistinct ID（対象が人物の場合）またはグループキー（対象がグループの場合）が含まれているかを尋ねてください。マッピングが何もせずに終わる最も一般的な原因はこれです。そのため、確認せずに id や user_id のような名前から推測しないでください。

ユーザーが確定する前に、同期に関する次の2つの特性を明確に伝えてください。

• PostHog にすでに存在する人物またはグループのみを更新します。どの対象にも一致しない行はスキップされ、実行結果には skipped_missing_person と報告されます。人物は作成されません。
• null 値は書き込まれず、スキップされます。 行の値が null の列は、そのプロパティを変更しません。null によってプロパティを消去したい場合、ウェアハウスプロパティでは対応できません。

3. 作成前にマッピング案を提示する

完全な column_property_map — {warehouse_column: property_name} — を作成し、ユーザーに承認を求めてください。デフォルトでは両側で同じ名前を使います。名前の変更はユーザーが決めることであり、推測で決めるべきではありません。

次の項目は案から除外し、除外した理由を伝えてください。

• 識別子の列。 その値は人物を識別するものであり、人物について説明するものではありません。
• $ で始まるものと、email、name、username。 これらは SDK が設定する ID プロパティであり、ウェアハウスから書き込むと、PostHog がすでに把握している情報を上書きする可能性があります。
• 人物プロパティとして機微な情報にあたる列。 パスワードハッシュ、トークン、内部監査列、人物プロフィール UI に表示したくない情報などです。ユーザーだけが自身のスキーマを把握しているため、黙って除外するのではなく、注意を促してください。

次に、競合を確認してください。既存の人物プロパティを読み込み、マッピング対象の名前がすでに存在する場合は、そのプロパティが同期のたびに上書きされることを伝えてください。custom-property-definitions-list には設定済みのウェアハウスプロパティが表示されるため、すでにマッピング済みのテーブルも確認できます。

列数の多いテーブルでは、これが特に重要です。20列のテーブルをそのままリストで提示しても、確認しにくいものになります。マッピングする項目、除外した項目とその理由、競合する項目に分けて案をまとめてください。

4. 作成する

定義を先に作成し、次にソースを作成します。

1. custom-property-definitions-create で target_type: person（または group と group_type_index）を指定し、display_type: text を設定します。名前には1つの列ではなく、プロパティのグループを表す名前を付けてください。定義は、ユーザーが UI で目にする行です。API では display_type が必須です。人物とグループを対象とする場合は text を使用してください。この場合は無視されます（プロフィールプロパティは生の $set／$group_set 値として書き込まれるため、アカウントプロパティの表示形式にのみ影響します）。
2. custom-property-sources-create で定義 ID、external_data_schema または saved_query のいずれか一方、完全な column_property_map を指定し、key_column には手順2で確認した識別子を設定します。

マッピングとバインディングは作成時にのみ設定できます。マッピングする列を変更するには、プロパティを削除して作成し直す必要があります。そのため、稼働中のマッピングを何度も調整するよりも、案をしっかり確認しておくことが大切です。

5. バックフィルと検証

有効なソースを作成すると、バックフィルが自動的に開始されます。既存のマッピングの場合は、custom-property-sources-backfill がテーブル全体を読み込み、過去の行を反映します。すでに実行中の場合は、処理がまとめられます。

次に custom-property-sources-runs-list を読み込み、ファネルを確認します。マッピングが「何もしなかった」理由は、ここで明らかになります。

ステージ	ここがゼロの場合の意味
rows_read	ステージングされたデータはありません — マッピングの作成後、テーブルが同期されていません
changed	すべての値が最後に送信された値とすでに一致しています。再実行しても何も起きないのが正常です
existing	行の識別子が人物またはグループに一致しませんでした — 通常はキー列が間違っています
produced	キャプチャに到達したデータはありません。skipped_missing_person を確認してください

行を読み込んでいるにもかかわらず existing: 0 と表示される場合、ほぼ間違いなくキー列が誤っています。

次の手間を省くためのメモ

• 同期はテーブル自体のスケジュールに従います。別途スケジュールを設定することはできないため、「どれくらいの頻度で更新されるか」はテーブルの同期頻度で決まります。
• 何度も失敗するソースは、5 回連続で失敗すると自動的に無効化されます。再度有効にすると、連続失敗回数がリセットされ、新たなバックフィルが開始されます。
• その場合、ソースを作成したユーザーに通知が届きます。そのユーザーが Customer analytics タスクを利用できる場合、PostHog はそのユーザーにタスクも割り当てます。タスクのダイジェストを有効にしている場合に限り、メールにもタスクが届きます。
• 「今すぐ同期」は基になるテーブルを実行します。同期テーブルの場合は実際に課金対象となるウェアハウス同期が行われ、マテリアライズドビューの場合はマテリアライズが行われます。安価な何もしない処理ではありません。custom-property-sources-runs-list で無料で確認できるマッピングを「チェック」するために呼び出さないでください。