用途:在 Amplitude 中构建图表时,用强类型、贴近图表构建器 UI 的 chart 参数表达,交由服务端编译,而不是手写原始 definition JSON。query_amplitude_data 只接受 chart 或 definition 之一,chart 为首选,definition 仅用于强类型模型未覆盖的图表类型(如 composition、revenueLtv)或无对应字段的高级参数。字段名为 snake_case,由服务端 Pydantic 校验。
主要能力:支持 segmentation、funnel、retention、sessions、data_table 等图表类型,共用 group_by、segments、date_range、interval、count_unique_by、name 等构件。Condition 支持 is、is not、contains、greater than、set 等操作符,scope 可为 event、user、group、session、derivedV2。日期范围必填,相对与绝对二选一,相对范围单位需与 interval 匹配。
使用方式:创建流程为先用当前 taxonomy 能力发现事件与属性名,再构建 chart,调用 query_amplitude_data,最后用返回的 chartEditId 调用 render_amplitude_chart 展示。修改或 fork 已保存图表时,用 search_amp_entities 找到图表 id,get_amplitude_charts 以 include: 'typed' 读回,编辑后带 chartId 调用 query_amplitude_data。get_amplitude_charts 的 include 有 link、typed、definition、data、guide 五种模式。
限制:编译器只校验结构,不校验 taxonomy;不存在的事件或属性名不会报错,而是返回数据为空的合法图表。组属性需用 group_type 且不加前缀,若被拒绝通常是后端属性注册表缺失,不应反复重试拼写。编译错误返回 400 并指出字段与修复提示,应只改该字段。结果为空时可检查名称与 scope、放宽日期范围、逐步去掉筛选,或确认属性聚合已放入 group_by。