creating-an-endpoint

创建端点

本技能将引导你通过正确配置创建新端点。端点将已保存的 HogQL 或洞察查询公开为可调用的 HTTP 路由——创建时选择的配置会影响成本、延迟以及调用方的集成方式。

物化的深入介绍位于 references/materializing.md。如果物化决策不明确，请查阅该文档。

何时使用此技能

-“为 [查询] 创建一个端点” -“将此洞察公开为 API” -“帮我把这段 HogQL 转换为可调用的端点”

• 新的调用方（移动应用、面向客户的仪表板、下游管道）需要 PostHog 数据，而用户正在选择交付方式

按顺序做出决策

1. 是否真的需要创建端点？

适合使用端点的情况：

• 外部系统（他人的代码）需要调用 PostHog 获取数据
• 查询是稳定的，而非探索性分析
• 查询的形态具有可复用性——同一查询使用不同参数

不适合使用端点的情况：

• 内部 PostHog 仪表板或洞察需要数据——直接使用洞察；端点只会额外增加你在内部并不需要的外部 API 接口
• 一次性、探索性分析——直接使用 execute-sql 工具（或 SQL 编辑器）

聚合操作繁重并不是避免使用端点的理由。端点本身就是已保存的查询；对于频繁调用的繁重聚合查询，启用物化往往是使用端点的_最佳_场景。

如果用户不确定，请询问是什么在调用端点，以及他们期望的数据形态是什么。

2. 选择名称

名称只能包含适用于 URL 的字符（字母、数字、连字符、下划线），必须以字母开头，最长 128 个字符，并且在项目内必须唯一。建议：

• 描述性优先于通用性——使用 weekly_active_users_by_org，而非 metrics
• 使用 Snake_case——与名称在代码路径和 URL 中的呈现方式一致
• 名称中不包含版本号——版本由端点本身管理
• 名称中不包含“endpoint”——多余

名称会出现在 URL 中：/api/projects/{team_id}/endpoints/{name}/run。之后无法轻易重命名（调用方依赖此路径）——创建时就选好名称。

3. 选择查询类型

有两种选项：

• HogQL（HogQLQuery）——用户编写的原始 SQL。通过 {variables.x} 语法定义变量，并根据 code_name 匹配。对于调用方关心响应确切列结构的新端点，推荐使用此选项。
• 洞察——封装现有的洞察定义。对 TrendsQuery、LifecycleQuery 和 RetentionQuery 的支持最好：这些查询可以物化，且细分项可以作为变量（仅适用于 Trends 和 Retention；Lifecycle 没有细分项）。其他洞察类型（例如 FunnelsQuery）可以内联运行，但不能物化，也不支持细分变量——如果需要其中任一功能，请将其改写为 HogQL。

HogQL 灵活性更高。只有在用户确实要重新发布现有洞察时才选择洞察（请参阅下文“从现有洞察创建”），而不是用它来构建新查询。

4. 决定哪些输入应设为变量

每次调用者使用时都可能变化的内容应设为变量；其余内容则硬编码在查询中。

对于 HogQL 端点，变量通过查询负载中的 code_name、type 和 default 声明。每次执行调用都要传入 { "variables": { "<code_name>": value } }。

常见模式：

• 时间范围：date_from、date_to，或单个整数 lookback_days
• 身份筛选：user_id、account_id、team_id
• 除 limit / offset 以外的分页控制（运行端点已将这两项作为一等参数）

对于洞察端点，细分属性充当变量（仅适用于 Trends 和 Retention，Lifecycle 不支持细分）。将细分属性名称作为键传入。date_from / date_to 仅在非物化洞察端点上可作为变量传入；物化端点会将日期范围固化在视图中，因此调用者无法调整时间窗口。

避免：

• 会改变结果形状的变量——保持列稳定。如果调用者需要根本不同的结果形状，请提供单独的端点。
• 绕过安全机制的变量——不要公开允许调用者注入任意 SQL 的 where_clause 变量。

基于现有洞察创建

没有服务端操作可以“根据洞察 N 创建端点”。要实现这一点：读取洞察的查询（通过洞察工具），将该查询传给 endpoint-create，并将洞察的短 ID 设为 derived_from_insight，以记录其来源。之后，端点会拥有自己的查询副本——后续对洞察的修改不会传递到端点。如果要从头开始？先使用洞察工具 / sql-variables 构建查询，再据此创建端点。

5. 设置 data_freshness_seconds

这个字段有两项用途，因此要谨慎设置：

1. 缓存 TTL——结果会从缓存中提供，直到缓存数据达到指定秒数。
2. 物化刷新频率——对于物化端点，该值也决定数据仓库重新计算物化视图的频率。

因此，值越低，数据越新，重新计算 / 刷新的成本也越高；值越高，这两方面的成本越低，但数据也越陈旧。

该值必须是以下固定值之一：900（15 分钟）、1800（30 分钟）、3600（1 小时）、21600（6 小时）、43200（12 小时）、86400（24 小时，默认值）、604800（7 天）。不支持低于 15 分钟的选项——900 是下限。

data_freshness_seconds	适用场景
900–1800	可选的最新数据——适用于数据陈旧情况会直观可见的仪表板
3600–43200	大多数情况——足以满足产品使用需求，且重新计算成本较低
86400–604800	报告、每周 / 每日指标，以及任何按较长周期汇总的数据

除非用户明确需要更新鲜的数据，否则优先选择较高的值。对于物化端点，请记住，此值也决定刷新频率。

6. 决定是否从第一天起就进行物化

完整决策流程请参阅 references/materializing.md。简要来说：

• 建议进行物化：端点调用频繁、延迟很重要，且用户可以接受与刷新间隔相当的数据陈旧程度（定时物化通常为 5–15 分钟，也可以按小时刷新）。
• 跳过物化：流量较低的端点、尚在探索阶段的新端点（暂时无法确定是否会被调用），以及对数据新鲜度要求极高的查询。

如果不确定，请先创建非物化端点，等使用情况稳定后再添加 is_materialized: true。这样可以避免为没人最终调用的查询支付物化成本。

工作流

1. 确认使用场景（上面的第 1 步）。如果它实际上不适合端点，请推荐替代方案。
2. 与用户商定名称。
3. 逐步检查查询——确认它是 HogQL 还是洞察，并确认列和结构是否合理。
4. 确定哪些内容应设为变量。向用户展示变量声明语法。
5. 根据用户对数据新鲜度的要求选择 data_freshness_seconds（不清楚时请询问）——并记住，它也决定物化刷新频率。
6. 发起物化调用。如果拿不准，就先不启用，之后再重新评估。
7. 使用商定的配置调用 endpoint-create。
8. 使用示例载荷调用 endpoint-run，确认响应结构。
9. 如果用户准备开始接入，请转到 consuming-endpoints-from-client-code。

交互示例

User: "I want to expose our monthly active users count as an API
       for our analytics partner"

Agent:
- "Quick check: is the partner going to call this on demand, or
   should we be pushing data to them? Endpoints are pull-only."
- User: "On demand"
- "Got it. A few choices:
   - Name: how about monthly_active_users? Lowercase, descriptive,
     no version baggage.
   - The query — is it HogQL or are you exposing an existing insight?
     HogQL gives you exact column control; insight reuses what you've
     already built.
   - What should the partner be able to filter by? Org, time window,
     both?
   - How fresh? If MAU drifts within a day is fine, we can cache
     results for 1-24 hours and serve almost everything from cache.
   - Materialisation: if the partner is going to hit this many times
     per day, materialising it would make responses near-instant.
     The trade-off is ~10-15 minute staleness.

   What's your starting point on these?"

[user picks: HogQL, lookback_days + org_id variables, 3600s TTL,
 not materialised yet]

- endpoint-create monthly_active_users {query, variables, ...}
- endpoint-run with sample payload {org_id: "test", lookback_days: 30}
- "Created and tested. Want help wiring up the client code?
   That's consuming-endpoints-from-client-code."

重要说明

• 名称会出现在 URL 中。 之后更改名称需要迁移调用方。请谨慎选择。
• HogQL 端点比洞察端点更灵活。 默认使用 HogQL，除非用户有特定理由需要封装现有洞察。
• 没有默认值的变量会在调用时导致失败。 创建时务必设置默认值，这样无需指定每个变量，也能在 Playground 中测试端点。
• 物化端点要求传入所有变量。 不传变量的调用会被拒绝——这是有意设计的（出于安全考虑：防止返回未筛选的数据）。建议物化时，请同时告知用户哪些变量会变为必填项。 （物化端点上的可选/部分变量是已知限制，PostHog 团队计划解除这一限制——如果这阻碍了用户，请通过 agent-feedback 工具向他们反馈。）
• 不要对不符合条件的查询启用物化。 先使用 endpoints-materialization-preview 确认是否符合条件，并查看任何拒绝原因。
• 端点并非永久稳定。 用户更改查询时会自动创建新版本（旧版本仍可通过 ?version=N 访问）。data_freshness_seconds 和物化设置均按版本生效。请根据端点的演进调整这些设置。
• 建议调用方固定使用某个版本。 告诉用户使用 ?version=N 调用，而不要依赖“最新”版本——这样，未来编辑查询（会生成新版本）就不会悄悄改变结果。用户验证新版本后，再主动升级固定的版本号。
• 通过 agent-feedback 分享遇到的阻碍。 如果某项限制造成了问题（资格规则、必填变量、TTL 枚举），请向 PostHog 团队反馈——这有助于改进产品和这些工具。