reviewing-warehouse-suggestions

审核数仓建议

PostHog 每天都会根据项目读取视图和表的情况计算数仓建议。 每条建议针对一个视图或表。 其 payload 包含接受建议后将创建或更改的所有内容。

1. 查找建议

调用 warehouse-suggestions-list 并设置 status=proposed。 结果按优先级排序，请从顶部开始查看。 如果列表为空，请调用 warehouse-suggestions-status：它会说明建议是已关闭、仍在收集读取历史，还是不符合条件。

对于用户想要讨论的建议，请调用 warehouse-suggestions-get。 其中的 evidence 包含相关的读取次数。

2. 根据建议自身的数据进行说明

使用 payload 字段告诉用户接受建议会产生什么效果以及需要付出什么代价。 不要编造评分或置信度。

• materialize：该视图读取频率足够高，存储其结果可以节省计算开销。
  • saves_seconds_per_month 和 saves_bytes_per_month 表示读取不再产生的开销。
  • 物化会增加定期刷新开销，而这些数值已扣除这部分开销。
  • freshness_today_seconds 和 freshness_after_seconds 表示当前和物化后的数据可能有多旧。
  • refresh_interval_seconds 是建议的刷新间隔。refresh_interval_basis 说明间隔无法缩短的原因：source_sync（数据源同步频率不够快）、fastest_schedule（PostHog 刷新视图的频率不会更高）、read_rate（用户读取视图的频率不会更高），或 savings（缩短间隔的成本高于节省的成本）。
  • 当每次刷新只需读取新行（由 incremental_key 指定），并通过 unique_key 更新行时，refresh_mode 为 incremental。否则为 full，每次刷新都会重建整个表。
• unmaterialize：该物化视图读取频率很低，刷新它的成本高于每次读取时重新计算的成本。
  • refresh_seconds_per_month 和 refresh_bytes_per_month 表示该视图当前的刷新成本。
  • live_seconds_per_month 和 live_bytes_per_month 估算每次读取都计算该视图时的成本。该估算按每次读取都完整刷新一次计算，因此数值偏高。
  • read_seconds 表示之后每次读取所需的时间。十分之九的刷新都在这段时间内完成。告诉用户读取速度会因此大约慢这么多，而且每次读取都会获取当前数据，而不是上次刷新时的数据。
  • 接受建议会停止刷新并删除已存储的表。视图定义会保留，因此之后可以再次物化。
  • 接受时出现 409 错误，表示自建议生成后视图发生了变化，例如另一个视图现在会读取该视图。向用户说明原因，不要重试。
• certify：许多人会从多个位置读取此视图或表。使用 evidence 中的读取次数。
• deprecate：没有人读取此物化视图，但它仍在刷新。refresh_seconds_per_month 和 refresh_bytes_per_month 表示这部分成本。接受建议会在数据目录中将其标记为弃用、停止刷新并删除已存储的表。视图定义会保留，因此之后可以再次物化。若要让它继续刷新，请传入 keep_materialized: true。接受后，created_asset.stopped_materialization 会说明刷新是否已停止：如果有其他视图读取该视图，或其刷新结果被用于人员属性、目标位置或工作流，刷新就会继续运行。

3. 接受前更改物化建议

该负载只是一个起点。 要更改它，请在接受工具中传入同名的负载字段。 省略的字段会保留建议值。

• 使用其他间隔：传入 refresh_interval_seconds。
• 使用全量而非增量，或反过来：传入 refresh_mode。
• 使用其他键：
  1. 使用 view-get 读取视图的查询。
  2. 使用该查询，以及用户想要的 incremental_key 和 unique_key，调用 view-check-incremental。 不提供键时，该工具会列出 key_candidates 和 unique_key_candidates。
  3. 仅当检查返回 eligible: true 时，才使用这些键接受。否则，请向用户说明 blockers。
• 较晚到达的行：传入 lookback_seconds，以便每次刷新都重新读取此前相应时间范围内的数据。

只有在确定键无误时，PostHog 才会建议采用增量刷新。 即使建议为 full，用户选择的键通过检查后，仍可进行增量刷新。 唯一键必须包含查询分组所依据的每一列。

4. 接受或忽略

使用 warehouse-suggestions-accept-prepare 接受；用户输入 confirm 后，再调用 warehouse-suggestions-accept-execute。 服务会根据视图当前的查询检查每个选项：

• 400 错误会指出被拒绝的字段及原因。向用户展示原因，并询问要更改什么。
• 409 错误表示视图在提出建议后发生了变化，因此建议的键已不再适用。可选择全量刷新，或使用 view-check-incremental 检查过的键。

使用 warehouse-suggestions-dismiss 和原因（not_useful、not_now 或 other）忽略建议。 warehouse-suggestions-resume 会重新显示已忽略的建议。