本文字数10321估计阅读时间26 分钟作者Fiveonefour本文在公众号【ClickHouseInc】首发L;DR借助 AI可以大幅加速将分析型工作负载从 Postgres 迁移到 ClickHouse。想让你的智能体真正发挥作用需要为它们构建合适的运行环境1. 代码一切尽量代码化这是智能体最擅长的领域2. 节奏建立快速且安全的反馈闭环3. 上下文通过智能体技能和参考资料注入 ClickHouse 最佳实践最后用像 MooseStack 这样的智能体运行框架把这一切整合起来避免产出质量低劣的 AI 结果。想直接进入实操这里有一份实用的分步指南https://docs.fiveonefour.com/guides/performant-dashboards/tutorial。你的仪表盘开始变慢Postgres 在面对分析查询时逐渐成为瓶颈。你已经意识到Postgres 搭配 ClickHouse 才是正确的架构选择。你希望继续用 Postgres 承载事务型工作负载同时将分析型工作负载迁移到 ClickHouse。你期待构建统一的数据栈Postgres ClickHouse 无缝协同各司其职在合适的场景使用合适的工具。那么究竟该如何将分析型工作负载从 Postgres 迁移到 ClickHouse你希望让 AI 来承担这项繁重的工作。我们也认同这一点。但现实是大多数 AI 辅助的迁移最终都会产生大量不可用的结果。我们在为客户迁移数千张表和查询的过程中已经深刻体会到了这一点。本文将探讨如何让你的 AI 智能体在将分析负载从 Postgres 迁移到 ClickHouse 的过程中真正高效、可靠地工作。一个有效落实 ClickHouse 最佳实践的 AI 智能体ClickHouse 迁移理想与现实如果你只是做一个玩具项目或 POC普通的 AI 智能体或许已经足够胜任。真正的挑战在于构建面向生产环境的系统。生产系统往往复杂充满各种边界情况和历史包袱。而你追求的也不仅仅是“能跑起来”还需要系统具备良好的集成性、可扩展性、可靠性以及极致的性能。这意味着必须充分考虑整个系统的细节和特性。如果你希望在生产应用中充分发挥 ClickHouse 的能力那么通常需要(1) 针对 OLAP 性能重新设计数据模型(2) 将原本在查询阶段完成的 JOIN 和聚合重构为在写入阶段通过 Materialized Views 实现(3) 优化 API 层中的查询语句以及 (4) 将变更逐层传递并在前端组件中完成验证和测试。因此问题不仅仅是“我的智能体能不能写 ClickHouse SQL”而是“我是否为智能体提供了在复杂集成应用栈中高效工作的完整环境” 要实现这一点你需要为智能体提供必要的接口、工具、技能、代码和上下文使其能够快速且安全地迭代直至成功。换句话说你需要一个面向 Postgres ClickHouse 的“智能体运行框架”。当然你也可以自行设计这样的框架。但在本文中我们将演示如何直接使用 MooseStackClickHouse 原生的开源开发者框架作为智能体运行环境帮助你的智能体在 Postgres ClickHouse 架构下顺利工作。从初创公司到大型企业我们已经看到这种方法能够在数天内完成生产级分析型工作负载从 Postgres 到 ClickHouse 的迁移而不是耗费数月时间。让我们深入探讨。如果你想直接进入实操阶段这里有一份分步指南https://docs.fiveonefour.com/guides/performant-dashboards/tutorial帮助你在 AI 的协助下将仪表盘迁移到 ClickHouse。代码一切代码化 - 让你的分析栈对 AI 清晰可见编码智能体擅长阅读、编写和审查代码。但当涉及到协调基础设施、跟踪数据库状态、管理 schema 演进以及构建真正生产级 ClickHouse 架构所需的各种工作时它们往往力不从心。解决之道是将统一的应用与数据栈整体视为一个以代码形式表达的系统。不要再依赖零散的 DDL 脚本、散落的 SQL 字符串或仅存在于团队记忆中的经验而是使用共享的、强类型对象来定义系统并明确声明依赖关系见下例。所有内容统一由 git 管理并完整存在于你的 IDE 和本地文件系统中——也就是编码智能体最熟悉、最擅长发挥能力的环境。import { MaterializedView, OlapTable, sql } from 514labs/moose-lib; import { sourceTable } from path/to/SourceTable; // could also be a view // Define the rows we want to serve to dashboards. // This is the schema of the destination ClickHouse table. // JSDoc comments embed as column descriptions in CH, // readable by agents querying the data. interface TargetSchema { id: string; /** Mean rating value computed across all submitted reviews with ratings. */ average_rating: number; /** Total number of valid reviews contributing to the average rating. */ num_reviews: number; } // Declare the destination serving table in code. export const targetTable new OlapTableTargetSchema(target_table, { orderByFields: [id], }); // Declare the OLTP - OLAP rewrite as a first-class object: // source table(s) - transformation - serving table. export const mvToTargetTable new MaterializedViewTargetSchema({ // Turn query-time aggregation into a precomputed rollup. selectStatement: sql SELECT ${sourceTable.columns.id}, avg(${sourceTable.columns.rating}) AS average_rating, count(*) AS num_reviews FROM ${sourceTable} GROUP BY ${sourceTable.columns.id} , // Explicit upstream dependencies (the “reads from” side of the graph). selectTables: [sourceTable], // Explicit downstream dependency (the “writes to” side of the graph). targetTable, // The name of the ClickHouse Materialized View. materializedViewName: mv_to_target_table, });在 MooseStack 中代码成为智能体与 ClickHouse 数据栈交互的默认接口。例如源表和物化视图都以强类型对象的形式声明在代码库中。这意味着智能体操作的是熟悉的 Typescript 模式更容易正确完成任务即便出错智能体生成的结果也只是代码改动可以通过 git 轻松回滚、演进和迭代——这正是编码智能体最适合处理的形式此外智能体还能复用并传播这些强类型数据模型例如传递到你的 API如 Express、Fastify、Nextjs、你的 MCP、前端应用或任何引用 ClickHouse 数据的下游系统。在底层这会形成一个显式且可复现的依赖图MooseStack 将其记录为 “InfraMap”并通过 MooseStack dev MCP 提供给智能体。当智能体修改源 schema 或 rollup 时不再需要猜测哪些下游模块会受影响——依赖关系清晰可见影响范围可以通过 MCP 即时从代码中获取。“一切代码化”让 ClickHouse 迁移从一次脆弱的数据库重写转变为一次标准的模块化代码重构。而这正是 AI 智能体最擅长解决的问题。节奏为 AI 驱动的 OLAP 迭代建立快速反馈闭环更进一步当整个系统都代码化之后你就可以围绕它构建高效的反馈机制。Boyd 定律指出在复杂环境中迭代速度往往比单次迭代的质量更重要。如果你期望一个 大语言模型 一次性完成整个迁移成功的概率并不高。理想情况下你应该在每一次增量改动后进行端到端验证包括 schema、rollup、API 查询以及仪表盘输出。这只有在反馈足够快的前提下才现实——而且必须非常快。如果每一次微调都需要部署到云端并进行一次数据回填才能发现问题那么 AI 的迭代速度将慢到失去价值。在 Postgres → ClickHouse 的迁移过程中MooseStack 为开发者和智能体提供了三层快速反馈机制在 IDE 中当智能体仍在编写代码时即可捕获 schema、类型和 ClickHouse SQL 错误。在本地开发环境moose dev中通过可热替换的基础设施、真实数据以及运行时日志和错误端到端运行完整的 OLAP 栈。在“预览分支”部署中在合并前在接近生产环境的云基础设施上验证系统行为与性能。IDE 反馈在运行之前捕获 schema、类型与 SQL 错误如前所述MooseStack 将表和视图作为代码库中的一等强类型对象进行管理因此 IDE 可以立即标记错误的字段引用。智能体可以利用这一能力获得几乎实时的反馈。例如一个 React 组件可能会从共享的 EventModel 中渲染字段// app/analytics/page.tsx import { getEvents } from moose; export default async function AnalyticsPage() { const events await getEvents(); return ( ul {events.map((e) ( li key{e.id} {e.id}: {e.amount} at {e.event_time.toISOString()} /li ))} /ul ); }MooseStack 的 OlapTable 对象用于声明对应的 ClickHouse 对象。在 OLTP → OLAP 迁移的数据建模优化过程中LLM 可能需要调整该数据模型// moose/models/events.ts import { OlapTable } from 514labs/moose-lib; export interface EventModel { id: string; amount: number; // agent change: renamed event_time - occurred_at occurred_at: Date; } // This declares the ClickHouse table in code. export const Events new OlapTableEventModel(events, { orderByFields: [occurred_at], });由于强类型约束这种修改会立即在前端触发错误并几乎实时反馈给智能体// app/analytics/page.tsx // ❌ IDE error: Property event_time does not exist on type EventModel li key{e.id} {e.id}: {e.amount} at {e.event_time.toISOString()} /li不仅如此除了类型安全机制并且根据所使用的 CLI 不同智能体还可以直接调用 MooseStack 的 LSP用于语法校验、自动补全和错误诊断。面向 AI 的本地开发反馈使用 moose dev 端到端运行完整 OLAP 栈许多真实应用中的问题只有当整个系统真正运行起来之后才会暴露出来mutation 异步失败、schema 以意料之外的顺序生效、数据以不符合预期的结构到达或者 rollup 在前端悄无声息地计算出错误的结果。因此智能体需要一个快速、低成本并且高度贴近生产环境的运行反馈闭环。它应该能够应用 schema将数据流经物化视图执行真实的 API 查询并验证仪表盘实际依赖的输出结果。理想的方式是在本地运行支持热重载的基础设施并配合真实数据。将完整的 ClickHouse Postgres 前端栈在本地端到端运行让验证成本足够低使智能体可以围绕真实问题持续迭代而不是凭空猜测。在 MooseStack 中这一切从下面这个命令开始moose dev该命令会在本地启动完整的 OLAP 栈包括 ClickHouse并在智能体编写代码的过程中实时自动推断并应用 schema 变更 DDL。这为智能体带来了两类额外的快速反馈运行时错误。例如如果应用无法连接到 ClickHouse或者某个转换在遇到异常数据结构时抛出异常JSON 往往是常见问题来源这些问题不再悄无声息。通过 moose dev它们会立即显示在控制台日志中让开发者和智能体在迭代过程中第一时间发现。MCP 验证。MooseDev MCP 为智能体提供了访问和检查本地开发服务器的工具使其能够回答“系统最终是否处于智能体预期创建的状态” 表和视图是否正确创建 查询转换后的输出是否符合预期 日志中是否包含对 LLM 有帮助的信息 智能体甚至可以通过 moose query 和 moose seed 插入测试数据验证数据流并在流程的任意阶段抽样检查结果。真实数据让这些验证变得有意义。如果没有真实数据你可能在玩具数据集上顺利“通过”测试却依然上线了错误的 rollup。这正是让 OLTP → OLAP 迁移对 AI 友好的关键智能体获得的是来自真实运行系统的快速反馈而不仅仅是代码成功编译带来的表面信心。上下文最佳实践、专业经验与模式 - 为智能体提供关键的迁移与 OLAP 背景当然智能体的效果取决于你提供的上下文质量。除了前面提到的实时反馈上下文之外还包括静态上下文来自现有 OLTP 栈的实现数据和文档需要迁移到 OLAP技能与指南针对 OLAP / 迁移场景的可复用实现模式参考实现展示在组织内部已经被验证为“正确方案”的实现方式静态上下文让智能体基于真实数据与业务模式工作在迁移场景中你的核心业务逻辑往往已经存在只是需要从 OLTP 架构迁移到 OLAP 架构。因此你需要将现有实现的完整上下文提供给智能体。同时还应提供足够的数据与背景使其能够在迭代过程中完成端到端验证。这包括schema、数据字典和数据文档源数据现有的存储过程或中间视图当前系统中的示例查询输入与输出我们的 Improving Dashboard Performance Guide 提供了一个入门套件你可以将其克隆到项目中用于整理以上四类上下文。其中包含预构建的提示和模板帮助你轻松调度智能体让它们收集具有代表性的测试请求与响应样本用于后续验证例如## Test case: short-name ### Request (curl) bash # Method: GET|POST # Path: /api/endpoint # Expected: HTTP 200 # Auth: Bearer token via $API_TOKEN (do not paste secrets) # Notes: timezone/order/pagination assumptions if relevant # Set once in your shell: # export API_BASE_URLhttp://localhost:4000 # export API_TOKEN... # GET (query params) curl -sS -G $API_BASE_URL/api/endpoint -H Authorization: Bearer $API_TOKEN -H Content-Type: application/json --data-urlencode param1value1 --data-urlencode param2value2 | jq . # POST (JSON body) curl -sS -X POST $API_BASE_URL/api/endpoint -H Authorization: Bearer $API_TOKEN -H Content-Type: application/json -d {param1: value1, param2: value2} | jq . ### Expected response json { REPLACE_ME: paste the full JSON response body here (verbatim from the running endpoint) } 提前准备好关键上下文可以显著降低迁移过程中的调试成本。在我们参与的 Postgres → ClickHouse 迁移项目中真实的查询结果为智能体提供了明确的参照系使其能够更快收敛到正确的 ClickHouse 数据模型减少盲目重写也避免“看起来没问题但其实是错的”情况。技能教会智能体如何正确实现 OLAP 迁移静态上下文让智能体理解你要做什么技能则教会它如何用 ClickHouse 把事情做好。MooseStack 的智能体运行框架内置了一系列经过实战验证的技能将 ClickHouse 最佳实践整理为适合智能体执行的规则帮助你在 Typescript 或 Python 应用栈中正确实现 ClickHouse。// skills/clickhouse-best-practices/SKILL.mdname: clickhouse-best-practices description: MUST USE when reviewing ClickHouse schemas, queries, or configurations. Contains 28 rules that MUST be checked before providing recommendations. Always read relevant rule files and cite specific rules in responses.// skills/clickhouse-best-practices/rules/schema-types-avoid-nullable.md title: Avoid Nullable Unless Semantically Required impact: HIGH impactDescription: Nullable adds storage overhead; use DEFAULT values instead这些规则在 ClickHouse 原有智能体技能主要聚焦于 SQL 层面的最佳实践之上进一步扩展覆盖了 OLAP 数据建模中那些复杂而专业的关键问题例如如何选择高效的 ORDER BY 字段、如何控制基数、如何正确处理 Nullability 以及其他类型相关细节。不妨亲自体验一下// data modeling best practices skills npx skills add clickhouse/agent-skills // for ClickHouse SQL npx skills add 514-labs/agent-skills // for Typescript or Python //Prompt: review and update my data models to implement more efficient OLAP best practices参考实现不要让智能体重复解决已经解决的问题即便拥有充分的上下文和技能如果缺乏具体范例智能体仍然可能“自创方案”。因此应当将智能体引导到已经体现目标架构的代码上例如一个语义 / 查询层query-layer示例展示如何在 typescript 抽象中构建可复用、具备 ClickHouse 感知能力的查询端到端示例应用如 MooseStack 示例moosestack/examples展示 schema、物化视图、API 与仪表盘如何在真实项目中协同工作这些示例会将智能体的思路锚定在目标 OLAP 架构上而不是原有的 Postgres 设计。当它遇到类似问题时会基于成熟的 OLAP 设计向前扩展而不是沿用 OLTP 思维反向改造。这大幅降低了结果的不确定性让 AI 辅助迁移更具规划性而非临场拼凑。例如上述查询层示例定义了一套面向服务的查询模型并在所有需要数据的仪表盘中统一复用export const eventsModel defineQueryModel({ table: Events, dimensions: { status: { column: status }, day: { expression: sqltoDate(${Events.columns.event_time}), as: day }, }, metrics: { totalEvents: { agg: sqlcount(*) }, totalAmount: { agg: sqlsum(${Events.columns.amount}) }, }, filters: { timestamp: { column: event_time, operators: [gte, lte] as const }, status: { column: status, operators: [eq, in] as const }, }, });这对迁移有两个关键意义。第一它将 OLAP 原生模式固化为结构化实现预聚合指标、显式维度以及受限过滤条件而不是散落在各个处理逻辑中的临时 SQL。第二它为智能体提供了一个可直接模仿的结构范式。智能体无需在迁移过程中临时发明新的查询抽象而可以在既有成熟方案上进行调整。顺带一提我们正在计划为 MooseStack 增加一个轻量级语义 / 指标层使其成为框架的核心能力之一灵感正来自这个 query-layer 示例。如果你有任何建议或需求欢迎在我们的社区 slack 中与我们交流。快速预览从本地到生产以代码为中心的本地开发流程并不是为了替代生产部署而是为了让你在上线前可以安全、高效地迭代。生产环境中的 ClickHouse 集群配置不同、数据规模更大、故障模式也更复杂。一个在 10,000 行数据下表现正常的物化视图在 1,000 万行数据规模下可能会暴露性能或资源问题。在实践中安全部署意味着在云端构建 staging 和 preview 环境。Moose Migrate 提供了一种以代码为基础、可选人工审核的部署路径用于将新的 ClickHouse 配置发布到云环境。希望通过一次 git push将本地的智能体迭代直接部署到云端Fiveonefour 的托管服务与 ClickHouse Cloud 集成提供自动化预览分支、托管的 schema 迁移、与 Github 及 CI/CD 的深度整合以及面向云端统一数据栈的智能体运行框架。现在即可免费注册。我们也对下一步充满期待让智能体能够直接检查云端部署。514 CLI目前处于 alpha 阶段旨在提供与人类调试 ClickHouse 工作负载时相同的能力包括实时日志流、查询 ClickHouse 系统表以及验证迁移与物化视图是否成功执行。这些检查能力将在未来几天和几周内陆续发布使云端部署在你的 AI 运行框架中实现端到端可观测并可由机器自动验证。如果你有兴趣参与 alpha 测试欢迎加入我们的 slack 并与我们联系。结论Postgres ClickHouse 构成了现代应用的统一数据栈在需要事务性能的地方提供速度在分析场景中提供毫不妥协的能力。借助合适的智能体运行框架例如 MooseStackAI 可以帮助你顺利完成这一架构升级。当统一数据栈以代码形式表达辅以紧密的反馈闭环并建立在 ClickHouse 最佳实践之上时智能体就能够安全迭代最终落地到真正可用于生产的结果。准备好在自己的环境中尝试了吗查看完整的分步指南了解如何借助 AI 智能体将分析型工作负载迁移到 ClickHouse。征稿启示面向社区长期正文文章内容包括但不限于关于 ClickHouse 的技术研究、项目实践和创新做法等。建议行文风格干货输出图文并茂。质量合格的文章将会发布在本公众号优秀者也有机会推荐到 ClickHouse 官网。请将文章稿件的 WORD 版本发邮件至Tracy.Wangclickhouse.com