Ghost 开源仓库 Tinybird Pipe 文件规范详解:从格式规则到真实生产示例
Ghost 开源仓库 Tinybird Pipe 文件规范详解:从格式规则到真实生产示例
Ghost 官方在其内置会员分析(Analytics)数据层中,使用 Tinybird 的 .pipe 文件来描述数据管道(Pipe):从事件数据源出发,经过逐级 SQL 节点(NODE)转换,最终对外发布为统计 API 端点(Endpoint)或落盘为物化视图(Materialized View)。本文以 .agents/skills/tinybird/rules/pipe-files.md 为骨架,结合 ghost/core/core/server/data/tinybird 下真实的 *.pipe 文件,系统讲解 Pipe 文件的通用格式规则、节点(NODE)、类型(TYPE)、命名约束、参数模板语法与跨管道引用机制,读完即可独立读懂并编写符合 Ghost 规范的 Tinybird Pipe 文件。
一、Pipe 文件在 Ghost 中的角色与存放位置
1.1 什么是 Tinybird Pipe
在 Tinybird 的数据建模体系中,一个 Pipe 是一段可复用的数据处理流:它由一串 SQL 节点串联而成,前一个节点的输出自动成为后一个节点的输入。Pipe 文件(.pipe)是 Tinybird CLI 项目中描述该数据流的"声明式配置文件",本地文件即事实来源(source of truth)。
Ghost 的会员站点分析功能正是建立在这一套 Tinybird 项目之上。在 ghost/core/core/server/data/tinybird 目录下,.pipe 文件按职责分目录存放:
endpoints/:对外发布为 API 端点的 Pipe(如api_kpis.pipe、api_top_pages_router.pipe等约 28 个);pipes/:被其他 Pipe 复用的中间管道与物化管道(如filtered_sessions_v2.pipe、mv_hits.pipe、mv_session_data_v2.pipe、mv_daily_pages.pipe等)。
从仓库文件可以发现一个常见的演进模式:Ghost 为同一分析指标维护了 v1 / _v2 / _v3 多版本 Pipe。例如 endpoints/api_kpis.pipe 是在用的"无后缀 v1 版本",而 endpoints/api_kpis_v2.pipe 顶部用注释明确标注"当前未启用,请修改无后缀 v1 版本,_v2 管道将在未来版本移除"。这说明:改动生产 Tinybird 端点时应遵循"非破坏性增量修改"原则,优先修改正在使用的版本,而不是新开一个实验版本。
1.2 Pipe 文件与其他规则文件的关系
Pipe 文件的编写并非孤立存在,.agents/skills/tinybird/SKILL.md 中的规则体系把它与 datasource-files.md(数据源文件)、endpoint-files.md(端点文件)、materialized-files.md(物化视图文件)等并列。其中:
- rules/pipe-files.md:通用 Pipe 格式规则(本文主题);
- rules/endpoint-files.md:
TYPE endpoint的专项要求与tb endpoint data测试方法; - rules/project-files.md:项目目录组织与数据分层架构。
二、Pipe 文件格式的六条核心规则
依据 pipe-files.md,一个合法的 Pipe 文件必须遵守以下格式约束。
2.1 规则一:Pipe 名称必须全局唯一
Pipe 名称即 .pipe 文件名(如 api_kpis)。由于 Pipe 之间可以互相引用(见下文第五部分),一旦重名会导致编译时无法确定引用目标。在 Ghost 仓库中,每个端点管道、物化管道都拥有不同的文件基础名,即使描述同一指标的不同版本也通过 _v2、_v3 后缀区分,从而保证引用名唯一。
2.2 规则二:节点名不得与 Pipe 名或任何资源名冲突
一个 Pipe 内的每个 NODE <name> 节点名需要在其可被引用的命名空间中保持可区分:
- 同一 Pipe 内节点名彼此不重复;
- 节点名不与所在 Pipe 的文件名重复(避免
FROM pipe_name引用管道与引用节点输出的歧义); - 节点名不与数据源(Data Source)名重复。
以 pipes/filtered_sessions_v2.pipe 为例,两个节点分别命名为 sessions_filtered_by_hit_attributes 与 sessions_filtered_by_session_attributes,均与管道名 filtered_sessions_v2 保持区分。
2.3 规则三:属性名必须顶格,不得缩进
DESCRIPTION、NODE、SQL、TYPE 等属性关键字必须从第 0 列开始书写;只有属性值正文在 > 之后进行缩进。观察真实文件:
- 在 endpoints/api_kpis.pipe 中,
TOKEN、NODE、SQL、TYPE全部顶格,而SQL >之后的 SELECT 语句整体向右缩进; DESCRIPTION >之后的描述文本同样缩进书写,例如 pipes/mv_hits.pipe 中TYPE MATERIALIZED与DATASOURCE _mv_hits也是顶格的。
这一约束的存在是因为 Pipe 解析器按"顶格关键字"切分章节;若属性名被缩进,解析器会把整段内容误判为前一节的值。
2.4 规则四:允许的 TYPE 值只有四类
TYPE 用于声明 Pipe(或其末节点)的种类,允许值仅限:endpoint、copy、materialized、sink。Ghost 仓库中的实际使用:
| TYPE 值 | 语义 | Ghost 仓库真实示例 |
|---|---|---|
endpoint |
管道对外发布为 HTTP API 端点 | endpoints/api_kpis.pipe 文件末节点 finished_data 后声明 TYPE ENDPOINT |
materialized |
管道输出持久化为物化数据源(Materialized View) | pipes/mv_hits.pipe 声明 TYPE MATERIALIZED 并配合 DATASOURCE _mv_hits |
copy |
管道按计划把数据复制到另一数据源(Copy Pipe) | 仓库未直接出现,属预留类型 |
sink |
管道把数据写到外部系统(Sink) | 仓库未直接出现,属预留类型 |
注意:Ghost 实际文件里书写为大写形式(TYPE ENDPOINT、TYPE MATERIALIZED),与规则文档示例中的小写(TYPE endpoint)风格略有差异,书写时保持与仓库现有文件一致的风格即可。
2.5 规则五:输出节点必须声明在 TYPE 章节中,或在最后一个节点
Pipe 的"输出"概念分两种情况:
- 有
TYPE的 Pipe:TYPE前紧邻的节点(通常是最后一个节点)就是这个 Pipe 的输出节点; - 无
TYPE的中间 Pipe:最后一个节点的输出就是整个 Pipe 的输出,供其他 Pipe 通过FROM <pipe_name>引用。
例如 endpoints/api_top_pages_router.pipe 的节点 router 是最后一个节点,随后紧跟 TYPE ENDPOINT,于是 router 节点的输出即成为端点响应;而 pipes/filtered_sessions_v2.pipe 末尾没有任何 TYPE,其最后一个节点 sessions_filtered_by_session_attributes 的输出自然成为该管道输出,可被上层 Pipe 直接 FROM filtered_sessions_v2 引用(见 api_kpis_v2.pipe)。
2.6 规则六:为关键节点补充有意义的多行 DESCRIPTION
规则文档给出了最小可用的范例:
DESCRIPTION >
Some meaningful description of the pipe
NODE node_1
SQL >
SELECT ...
TYPE endpoint
其中的 DESCRIPTION 可有多个,既可放在文件头描述整条 Pipe,也可挂在某个 NODE 之前描述该节点的职责。Ghost 的实践是对每个承担核心逻辑的节点都写明其业务语义。例如 pipes/filtered_sessions_v2.pipe:
NODE sessions_filtered_by_hit_attributes
DESCRIPTION >
Get sessions where at least one hit matches the hit-level filter criteria.
Hit-level filters (pathname, post_uuid, member_status, location) can vary across pageviews within a session.
A session qualifies if ANY of its hits match the specified criteria.
DESCRIPTION 的好处不仅是可读性:当 Pipe 发布为端点时,描述会进入端点的 OpenAPI 定义(可通过 <api_base_url>/v0/pipes/openapi.json?token=<token> 获取),是生成给消费者的 API 文档的一部分,因此"有意义的描述"具有真实的产品价值。
三、逐字段拆解一个真实端点 Pipe
把规则套用到 Ghost 当前实际在用的 endpoints/api_kpis.pipe,可以看到一个完整端点管道如何组织。
3.1 TOKEN 区:声明可访问该端点的令牌
TOKEN "stats_page" READ
TOKEN "axis" READ
TOKEN 顶格声明哪些访问令牌(Token)可以读取该端点。Ghost 的分析端点通常同时开放给 stats_page 与 axis 两类令牌,由上层服务按权限分配。
3.2 节点链:前序节点作为后序节点的临时表
端点内部按"时间序列 → 会话指标 → KPI 汇总 → 最终拼装"组织多个节点:
NODE timeseries:生成按小时或按天展开的时间骨架(单日查询按小时、多日查询按天);NODE session_metrics:FROM mv_session_data并inner join filtered_sessions,计算每次访问的is_bounce(是否跳出)与session_sec(会话时长);NODE data:以a.date分组汇总visits / pageviews / bounce_rate / avg_session_sec四个核心 KPI;NODE pathname_pageviews:当请求携带pathname/post_uuid过滤时,直接从物化数据源_mv_hits统计对应页面浏览量;NODE finished_data(末节点):用left join把指标与页面浏览量合并,产出端点的最终行集。
这些节点间的数据流不靠临时表落地,而是依靠"上一个节点的输出即下一节点的输入表"这一 Pipe 机制(如 from timeseries a、inner join session_metrics s),避免了在每个 SQL 里重复维护相同子查询。
3.3 TYPE ENDPOINT:声明输出与参数校验边界
NODE finished_data
...
TYPE ENDPOINT
当消费者请求该端点时,finished_data 的查询结果即为响应体,且所有在该 SQL 中用 {{ ... }} 声明的查询参数都会参与校验与转换(见下一节)。
四、Pipe 中的 SQL 模板与参数化
Tinybird 对 Pipe 内 SQL 的限制是"只读 SELECT + 严格参数化"。Pipe 文件中的 SQL 正文里,% 一行标志着开始进入模板语法,可混合使用三类模板元素(Ghost 的 api_kpis.pipe 中全部出现):
{{ ... }}参数绑定与类型声明
{{ String(site_uuid, 'mock_site_uuid', description="Tenant ID", required=True) }}
{{ Date(date_from, description="Starting day for filtering a date range", required=False) }}
{{ Array(member_status, "'undefined', 'free', 'paid'", description="Member status to filter on", required=False) }}
String / Date / Array 不仅声明参数类型,还提供默认值、描述与是否必填(required=True)。由于 Ghost 是强多租户应用,几乎所有分析查询都强制要求 site_uuid(Tenant ID)参数,这在 api_kpis.pipe 中体现为 required=True。
{% ... %}控制流
{% if defined(date_from) %} ... {% else %} ... {% end %}:根据调用方是否传入参数动态拼接 SQL,未传时回退默认时间窗(默认最近 7 天);{% set _single_day = defined(date_from) and defined(date_to) and day_diff(date_from, date_to) == 0 %}:预计算布尔量,单日查询走小时粒度分支;{% if gift_link == 'false' or gift_link == '0' %} ... {% else %} ... {% end %}:按参数取值选择不同的过滤条件。
{# ... #}注释:模板内的说明注释,如{# Filter from specified start date #},不会进入最终 SQL。
这种参数化方案让"一个 Pipe 服务多种粒度查询"成为可能:同一 api_kpis 端点既能按天出趋势,也能在单日场景下自动切成小时级粒度并正确处理时区边界(跨时区 timezone 参数 + toTimezone 转换),是典型的"把复杂逻辑推迟到 SQL 模板里做"的写法。
五、管道间的引用与物化输出
Pipe 规范并未把每根管道封闭起来,而是鼓励"小管道、可复用":
- 中间 Pipe 输出即数据源:
filtered_sessions_v2把"按会话/点击属性过滤会话"这件事封装成一次计算,上层端点用inner join filtered_sessions_v2 fs on fs.session_id = sd.session_id(见 api_kpis_v2.pipe)直接消费,无需重复过滤逻辑; - Materialized Pipe 输出持久化数据源:当某段计算代价高、被多个端点复用且允许一定延迟时,Ghost 会把它做成物化管道。pipes/mv_hits.pipe 的写法展示了物化管道的完整骨架:
NODE mv_hits_0 -- 从 analytics_events 提取原始事件字段(含大量 JSONExtractString 展开)
NODE mv_hits_1 -- 计算引用来源归并(source)、OS、浏览器等派生字段
TYPE MATERIALIZED
DATASOURCE _mv_hits -- 落盘的数据源名(带下划线前缀以标识"由管道生成")
物化后其他管道用 FROM _mv_hits 读取(api_kpis.pipe),避免了每次请求都重放全量 analytics_events。由此可见 TYPE 规则背后的设计意图:物化层(materialized)、过滤/清理层(中间 Pipe)与 API 层(endpoint)解耦,各自独立演进。
- 端点内按需路由到不同实现:endpoints/api_top_pages_router.pipe 展示了一个"路由器"端点——它不写聚合逻辑,而是根据是否携带会话级过滤参数,用模板分支把请求转给
api_top_pages(支持复杂过滤)或api_top_pages_v3(基于日级物化视图、查询更快),且注释说明"Query parameters cascade automatically to the underlying pipe"(查询参数自动级联到被调用的底层管道)。
六、编写后的验证与部署操作
Pipe 文件写完后,需要借助 Tinybird CLI 验证与发布(详见 rules/build-deploy.md 与 rules/endpoint-files.md 中引用的命令):
tb build:本地编译项目,能第一时间暴露 Pipe 命名冲突、FROM引用不存在、SQL 语法错误、非法TYPE值等问题;tb pipe data <pipe_name>/tb endpoint data <endpoint_name>:用参数直接调用 Pipe 或端点查看输出。规则文档特别强调:验证端点请使用tb endpoint data,因为它按真实消费者请求的方式执行,包含参数校验与输出格式化(tb pipe data不触发端点级校验);tb endpoint ls:列出所有端点及其 URL,核对路由与参数;tb deploy:把本地项目推送到 Tinybird Cloud 生产环境。需要说明的是,部署目标由项目根目录tinybird.config.json的dev_mode决定(local或branch),命令默认操作本地上下文,涉及云端时需显式指定--cloud或--branch=<branch-name>;tb info:排查凭证与连接上下文(确认.tinyb文件加载位置、当前 workspace、API/UI/ClickHouse 地址)。
这些 CLI 能力与 Pipe 规则配套使用:先用 tb build 把关"命名唯一、TYPE 合法、输出节点正确"这类静态规则,再用 tb endpoint data 把关参数化与返回结构是否满足消费方预期。
七、编写 Pipe 文件的对照清单
把 pipe-files.md 的核心规则整理为落地检查清单,可作为新增或改动 Pipe 时的自查依据:
| 检查项 | 要求 | 仓库佐证 |
|---|---|---|
| 文件名唯一性 | Pipe 基础名(含 _v2 等后缀)不与任何管道重复 |
api_kpis.pipe 与 api_kpis_v2.pipe 并存但互不冲突 |
| 节点命名 | 节点名 ≠ 本 Pipe 名、≠ 其他节点名、≠ 资源名 | mv_hits.pipe 中节点 mv_hits_0/mv_hits_1 与数据源 _mv_hits 不冲突 |
| 顶格排版 | DESCRIPTION/NODE/SQL/TYPE/DATASOURCE/TOKEN 不缩进,值内容缩进 |
api_kpis.pipe 全文 |
| TYPE 合法性 | 仅 endpoint/copy/materialized/sink 四类 |
TYPE ENDPOINT、TYPE MATERIALIZED |
| 输出节点 | 有 TYPE 时输出节点紧跟 TYPE 之前;无 TYPE 时最后一个节点即输出 | api_kpis.pipe 的 finished_data;filtered_sessions_v2.pipe 的末节点 |
| 描述文档 | 关键节点使用多行 DESCRIPTION,端点的描述会进入 OpenAPI |
filtered_sessions_v2.pipe、api_kpis_v2.pipe 的各节点 |
| SQL 合法性 | 只读 SELECT、模板参数化、% 起始模板段、{% %}/{{ }}/{# #} 正确配对 |
api_kpis.pipe 全文 |
| 改动策略 | 优先修改在用版本(无后缀 v1),实验版本需注明状态 | 多个 _v2 管道顶部的弃用说明注释 |
总结
Pipe 文件是 Ghost Tinybird 分析数据层的核心编排单元,其格式规范可概括为:唯一命名、顶格关键字、四类合法 TYPE、输出节点显式化、配合 TOKEN/DESCRIPTION/模板化 SQL 的声明式组合。读懂并遵守这些规则,既能保证改动被 tb build 顺利编译、被 tb endpoint data 正确校验,也能让数据管道保持与 Ghost 官方一致的"中间管道复用 + 物化层预聚合 + 端点层瘦身"架构风格。若需进一步深入,可继续阅读同目录下的 rules/datasource-files.md、rules/endpoint-files.md、rules/materialized-files.md 与 rules/sql.md,并结合 ghost/core/core/server/data/tinybird 下的 35 个 *.pipe 文件反复对照实践。