ms2data/malloy-publisher

发布者：Malloy语义模型服务器

https://github.com/malloydata/publisher/actions/workflows/build.yml

Publisher 是 https://github.com/malloydata/malloy 数据语言的开源语义模型服务器。它允许您定义一次语义模型，并在任何地方使用它们。

什么是Malloy？

Malloy 是一种开源的数据建模语言。它允许您定义丰富的语义数据模型——指定数据背后的含义、关系和上下文。

Malloy模型编码可信的业务逻辑（例如收入、活跃用户、流失率），让您可以根据业务而非原始SQL查询数据。这些模型是版本控制的、可组合的，并且可跨环境移植。

您可以使用 VS Code扩展 开发Malloy模型，该扩展提供了编写模型、运行查询和构建仪表板的便捷环境。

什么是Publisher？

Publisher 通过简洁的API提供Malloy模型服务，为工具、应用程序和代理提供一致、可解释且AI就绪的数据访问。

Publisher围绕熟悉且经过验证的工作流设计：

• 数据建模者 使用VS Code扩展在Malloy中定义可信业务逻辑，并使用Publisher服务器提供其模型。
• 数据消费者 使用Malloy的无代码Explorer、笔记本、自定义数据应用程序或AI代理探索和扩展该逻辑。

这反映了DBT和Looker等工具普及的建模者→分析师流程——现在为AI时代重新构想，并基于完全开放的基础设施构建。

重要性

如果数据背后的含义不明确，您就无法信任答案。

无论您是构建仪表板、部署AI代理还是启用临时分析，每种体验都依赖于对"MRR"、"LTV"或"活跃用户"等术语的共同理解。没有这个基础，洞察就是不一致的——或者是危险的错误。

Publisher通过将语义模型转换为可重用的数据API解决了这个问题。通过将Malloy的表达性建模语言与开源服务器和无代码数据分析UI相结合，Publisher使语义层对每个人都可访问、可治理和可扩展。

从语义模型到数据体验

每个Publisher体验都始于语义模型——用 Malloy 编写并通过Publisher服务器提供。您可以使用 https://github.com/malloydata/malloy-vscode-extension 创建自己的模型，或使用 https://github.com/malloydata/malloy-samples 存储库中的示例模型之一，该存储库作为子模块包含在此 repo 中。

服务模型

要使您的语义模型生效，您可以在本地运行Publisher服务器，并使用浏览器中的Publisher应用浏览您的模型。该应用提供了强大的无代码界面，用于探索和查询模型。

有关如何设置、构建和配置Publisher服务器的说明，请参见：

• 构建和运行说明
• 服务器配置

Publisher的默认服务器配置提供 https://github.com/malloydata/malloy-samples%E3%80%82%E6%9C%8D%E5%8A%A1%E5%99%A8%E8%BF%90%E8%A1%8C%E5%90%8E%EF%BC%8C%E6%82%A8%E5%8F%AF%E4%BB%A5%E9%80%9A%E8%BF%87%E4%BB%A5%E4%B8%8B%E5%9C%B0%E5%9D%80%E8%AE%BF%E9%97%AE%E5%BA%94%E7%94%A8%EF%BC%9A

• Publisher应用（REST API + UI）： http://localhost:4000

一旦您的模型被提供，它就成为各种数据体验的基础——无代码分析、笔记本、AI代理等。以下部分展示了这些体验在实践中的工作方式：

临时数据分析

模型发布后，分析师可以在Explorer中打开它，这是内置在Publisher应用中的可视化查询构建器。Explorer允许分析师：

• 浏览语义源、维度和度量
• 点击构建查询和运行嵌套逻辑
• 检查和理解底层Malloy和SQL
• 保存和共享可重用视图——无需编写代码

🎥 演示视频： 观看Explorer实际操作 →
📖 文档： Explorer文档 →

基于笔记本的仪表板

使用Malloy笔记本（.malloynb文件）直接从语义模型创建可共享的、代码优先的仪表板。这些仪表板与模型一起版本化，可以包含文本、图表和可重用视图——全部通过Publisher呈现。

• 非常适合需要可重复性和透明度的技术利益相关者
• 支持实时查询和图表渲染
• 笔记本可读、可检查且易于迭代

🎥 演示视频： 笔记本演练 →
📖 文档： Malloy笔记本 →

基于MCP的AI数据代理

Publisher通过模型上下文协议（MCP） 公开您的语义模型，使AI代理能够：

• 发现可用的源、维度和视图
• 基于模型提出格式良好的问题
• 获取包含完整元数据、查询和诊断的有意义响应

这使Claude、Cursor或自定义代理等工具能够使用您的定义生成准确、可解释的查询——而非猜测。

🎥 演示视频： MCP + AI代理演练 →
📖 文档： AI代理与MCP指南 →

嵌入式数据应用

使用 Publisher SDK，您可以构建丰富的数据应用程序——无需重建查询引擎或重写业务逻辑。Publisher应用本身就是基于此SDK构建的，您可以对其进行改造以：

• 创建内部工具或面向客户的仪表板
• 构建具有受治理数据访问的自定义UI
• 将图表或浏览器嵌入任何React应用

🎥 演示视频： 使用SDK构建应用 →
📖 文档： 嵌入式数据应用指南 →

遗留BI工具（即将推出）

Publisher很快将支持SQL兼容接口（例如Postgres有线协议），允许您连接遗留BI工具，如：

• Tableau
• Power BI
• Metabase
• Superset

这些工具将能够直接查询您的语义模型——获得一致性并减少重复逻辑，而无需改变团队的工作方式。

📖 文档（早期草稿）： 传统BI仪表板 →

架构概述

Publisher由三个主要组件组成：Publisher服务器（API和后端，现在包括MCP支持）、Publisher SDK（UI组件）和Publisher应用（参考数据应用实现）。

下图说明了Publisher组件的组成以及它可以支持的工具和应用程序。

1. Publisher服务器（packages/server/）

• 核心后端： 这是Publisher的核心。它是一个服务器应用程序，负责加载和管理Malloy包，这些包封装了您的语义模型。

• Malloy集成： 它利用Malloy运行时解析.malloy文件，理解其中定义的丰富语义模型（包括关系、计算和业务上下文），并将Malloy查询编译为SQL以在目标数据库（BigQuery、***、Trino、DuckDB、Postgres、MySQL）上执行。

• API层： Publisher服务器公开两个主要API接口：

  • REST API：
    • 用途： 供Web前端（Publisher应用/SDK）用于浏览包、模型和执行查询。
    • 规范： 在 api-doc.yaml 中定义。
  • 模型上下文协议（MCP）API：
    • 用途： 允许AI代理和其他MCP客户端（如 https://github.com/modelcontextprotocol/inspector 或兼容应用程序）与Malloy资源（项目、包、模型、源、视图、笔记本）交互并以编程方式执行查询。
    • 规范： 遵循 MCP 2025-03-26 规范修订版。包括提供资源元数据和带有建议的详细错误消息。
  • SQL API（即将推出）：
    • 用途： 连接您现有的工具。

• Malloy包格式： Publisher服务器基于Malloy包格式加载语义模型、笔记本和转换。此格式旨在与标准开发实践无缝集成。

  • 目标：通过标准实践实现可扩展性和治理： 使工程师能够使用熟悉的工作流（本地开发、CI/CD）和分发机制（如包、容器镜像、注册表）管理、版本化、测试和分发其数据转换和语义模型。这旨在将数据开发扩展到远远超出当前临时方法的限制。至关重要的是，利用这些标准软件工程实践提供了一种自然的治理形式。当受信任来源将版本化包推送到中央存储库或注册表时，该特定版本实际上成为供消费的受祝福或"治理"定义。这与传统数据目录或BI工具实现类似级别的数据资产信任和治理所需的复杂、通常是定制的流程形成鲜明对比。
  • 结构： Malloy包当前定义为包含以下内容的目录：
    • 一个或多个定义数据模型、查询和转换的.malloy文件。
    • 可选地，一个或多个.malloynb文件（Malloy笔记本），用于临时分析、探索和类似仪表板的演示。
    • 一个publisher.json清单文件。
  • 清单（publisher.json）： 包含有关包的元数据。目前，它支持name、version和description字段。随着Publisher的发展，此架构将显著扩展，以更好地支持依赖管理、版本控制和与包/容器注册表的集成，进一步加强治理模型。

2. Publisher SDK（packages/sdk/）

• UI组件库： 一组可重用的React组件，旨在构建与Publisher服务器的RESTful API交互的用户界面。
• 可嵌入： 旨在导入并用于其他基于React的数据应用程序中，使开发人员能够轻松添加Malloy模型浏览和查询功能供人类用户使用。
• 服务器通信： 处理向Publisher服务器的REST API获取数据和发送查询请求。

3. Publisher应用（packages/app/）

• 参考实现： 使用Publisher SDK构建的独立Web应用程序。
• 功能： 允许用户连接到运行中的Publisher服务器实例（通过REST API），浏览Malloy包，查看模型内容，并运行查询。分析师还可以生成可嵌入的代码片段或深入临时探索。
• Explorer： 一个无代码查询构建器，允许分析师在不编写SQL的情况下探索和扩展Malloy模型。Explorer使非技术用户能够提出有意义的、模型驱动的问题——完成从治理模型到自助数据分析的循环。Explorer文档 →
• 目的： Publisher应用不仅仅是一个演示——它是一个专业级、开源的数据探索工具。同时，它作为参考设计，用于在Malloy和Publisher之上构建您自己的数据应用程序。借助Publisher及其SDK，开发人员可以快速构建可信、可组合、AI就绪的数据体验。

构建和运行说明

无代码

如果您只想运行Publisher而不修改代码，可以直接通过bunx或npx运行：

sh
npx @malloy-publisher/server --port 4000 --server_root /path/to/malloy_packages

要运行指向Malloy示例的服务器：

sh
git clone https://github.com/ms2data/malloy-samples
npx @malloy-publisher/server --port 4000 --server_root .

Docker

或者，您可以在本地启动容器或使用Docker自托管。

安装Docker后，在包含您数据的新文件夹中，创建一个名为publisher.config.json的文件，内容如下：

json
{
   "frozenConfig": false,
   "projects": {
      "malloy-samples": "/publisher/malloy-samples"
   }
}

该文件将告诉publisher在哪里查找Malloy示例，您可以将其克隆到新文件夹中：

sh
git clone https://github.com/ms2data/malloy-samples

然后运行以下命令，将新克隆的示例与Docker容器链接：

sh
docker run -p 4000:4000 \
   -v ./publisher.config.json:/publisher/publisher.config.json \
   -v ./malloy-samples:/publisher/malloy-samples \
  publisher

然后，在浏览器中打开http://localhost:4000继续设置。

您可以通过附加额外的卷并在配置文件中引用它们来添加更多自己的项目。

代码方法

按照以下步骤构建Publisher组件并在本地运行服务器。此项目使用 bun 作为JavaScript运行时和包管理器。

1. 初始化和更新Git子模块：

Publisher存储库使用Git子模块包含示例Malloy模型（当前是malloy-samples的分支）。这些示例用于测试和演示Publisher的功能。

首先，初始化已注册的子模块：

bash
git submodule init

然后，更新子模块以获取其内容：

bash
git submodule update

2. 安装依赖项：

使用bun安装所有必要的项目依赖项（包括服务器、SDK和应用的依赖项）：

bash
bun install

3. 构建项目：

将所有包（服务器、SDK、应用）的TypeScript代码编译为JavaScript：

bash
bun run build:server-deploy

4. 启动Publisher服务器：

运行编译后的服务器代码。默认情况下，这将在端口4000上启动REST API服务器，在端口4040上启动MCP服务器。服务器将加载在子模块中找到的Malloy包。

bash
bun run start

启动后，您通常可以在 http://localhost:4000 访问Publisher应用（如果运行），在 http://localhost:4040