setting-up-warehouse-properties

设置数据仓库属性

数据仓库属性会将数据仓库表或物化视图中的列写入匹配的个人或群组，并沿用该表的现有同步计划。它们可以替代发送 $set identify 事件的 cron 任务。

映射就是全部工作。值得映射的大多数表都很宽，因此工作重点是决定哪些列要成为属性，以及属性的名称，而不是发起大量 API 调用。一个来源就能承载完整映射：custom-property-sources-create 会在单个请求中接收完整的 column_property_map，因此绝不要逐列循环调用。

何时使用此技能

• “将 postgres.customer_attributes 中的列同步到个人属性”
• “我们每天从数据仓库发送一次 identify 任务，PostHog 能否直接拉取？”
• “将此表映射到个人”／“将数据反向 ETL 到 PostHog”
• 用户正在查看 Data → Warehouse properties，并希望映射整张表

如果表尚未在数据仓库中，请改用 setting-up-a-data-warehouse-source。此技能适用于数据已开始同步之后。

工具

工具	用途
external-data-schemas-list	查找已同步的表及其 schema id（external_data_schema 绑定）；此处不包含列
external-data-schemas-retrieve	按 schema id 读取一个已同步表的列及类型
view-list	查找物化视图及其列 schema（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 会提供 schema id（external_data_schema 绑定），而 external-data-schemas-retrieve 会返回该 schema 的列及类型。

对于物化视图，view-list 会查找视图及其列 schema，而 view-get 会按 id 返回某个视图的列；视图使用 saved_query 绑定，并且必须已经物化，因为未物化的视图没有可读取的数据，创建调用也会拒绝它。

2. 选择标识符列，并说明它为何重要

询问哪一列保存 PostHog distinct ID（个人目标）或 group key（群组目标）。这是导致映射悄无声息地不起作用的最常见原因，因此不要仅凭 id 或 user_id 这样的名称猜测，务必先确认。

在用户确认之前，有两项同步行为值得明确说明：

• 同步只会更新 PostHog 中已存在的个人或群组。不匹配任何对象的行会被跳过，运行结果会将其报告为 skipped_missing_person。同步不会创建个人。
• Null 值会被跳过，而不会写入。 如果某一行的某列为 null，该属性会保持原样。如果用户希望通过 null 清除属性，那么仓库属性无法实现这一点。

3. 先提出映射方案，再创建任何内容

构建完整的 column_property_map — {warehouse_column: property_name} — 并提交给用户批准。默认两侧使用相同的名称；是否重命名由用户决定，不要擅自猜测。

从方案中排除以下内容，并说明排除原因：

• 标识符列。 其中的值用于识别个人，而不是描述个人。
• 任何以 $ 开头的内容，以及 email、name、username。 这些是由 SDK 设置的身份属性，从仓库写入可能会覆盖 PostHog 已知的信息。
• 作为个人属性会涉及敏感信息的列。 密码哈希、令牌、内部审计列，以及用户不希望显示在个人资料 UI 中的任何内容。请标记这些列，而不要悄悄排除，因为只有用户了解自己的架构。

然后检查冲突：读取现有个人属性，并指出任何已存在的映射名称，因为同步每次运行都会覆盖这些属性。custom-property-definitions-list 会显示已配置的仓库属性，因此你也可以发现已经映射过的表。

宽表正是这项检查至关重要的情况 — 将包含 20 列的表直接列成一份清单，无法供用户审查。请将方案分组列出：将要映射的内容、排除的内容及其原因，以及冲突项。

4. 创建

先创建定义，再创建来源：

1. 使用 custom-property-definitions-create，设置 target_type: person（或使用 group 并设置 group_type_index）、display_type: text，并使用描述一组属性而非单列的名称 — 用户在 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，几乎总是键列选错了。

减少来回沟通的注意事项

• 同步遵循表本身的计划。它不能单独安排计划，因此“多久更新一次”的答案取决于表的同步频率。
• 如果某个来源连续多次失败，在连续失败五次后会自动禁用。重新启用会重置失败次数，并触发新的回填。
• 发生这种情况时，创建来源的人会收到通知。如果他们可以使用 Customer analytics tasks，PostHog 还会为他们分配一项任务。只有在他们启用了任务摘要的情况下，该任务才会发送到邮箱。
• “立即同步”会运行底层表；对于同步表，这会执行实际的、按用量计费的数据仓库同步；对于物化视图，则会执行物化操作。这不是零成本的空操作——如果 custom-property-sources-runs-list 能免费解答问题，就不要调用此操作来“检查”映射。