Ghost 开源仓库 Tinybird Pipe 文件规范详解:从格式规则到真实生产示例

原创2026-09-08 09:47:541,607 阅读
文章标签:CMS后端前端

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(物化视图文件)等并列。其中:

二、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 的"输出"概念分两种情况:

  1. 有 TYPE 的 Pipe:TYPE 前紧邻的节点(通常是最后一个节点)就是这个 Pipe 的输出节点;
  2. 无 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 中全部出现):

  1. {{ ... }} 参数绑定与类型声明
{{ 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。

  1. {% ... %} 控制流
  • {% 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 %}:按参数取值选择不同的过滤条件。
  1. {# ... #} 注释:模板内的说明注释,如 {# 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 文件反复对照实践。

登录后查看全文
Ghost