课程Apache Doris 黑客松自主安排进度 · 随时开始 · 无需报名

赛道 A · 任务 A2

询问 Doris 通过 MCP

将 Doris 接入您正在使用的 AI 助手，让它执行真实 SQL，回答实际问题。

45–90 分钟
新手友好
Python 3.12+ · 任意 MCP 客户端
欢迎使用 AI 工具

获取入门包启动 Doris

遇到问题？ 可在 #dev 提问，频道位于 Apache Doris Slack。维护者和其他参与者会提供帮助。

准备环境

了解构建目标、Doris 如何简化实现，并启动集群。

构建目标

让 AI 助手成为 Doris 数据分析助手。

Apache Doris MCP Server 可将集群接入支持 MCP 的助手。连接后，让助手探索黑客松数据、编写 SQL，并回答平时通过看板分析的问题。

完成一套可运行的配置，让您的 MCP 客户端通过官方 Doris MCP Server 1.0 连接本地 Doris，并用简短说明展示助手能够：

自行发现 hackathon 中的数据表，
编写并执行 SQL，回答至少三个数据问题，
拒绝破坏性请求，因为服务端和用户均为只读。

界面草图待构建的界面 · 线框图，非实际截图

草图位于代码面板顶部

Doris 为何适合这个项目

默认按只读方式设计。 Doris MCP Server 1.0 仅提供只读能力，Doris RBAC 始终是最终权限约束。
八个领域，渐进披露。 包括 catalog、query、cluster、pipeline、 search、governance、lakehouse 和 semantic，通过渐进披露让模型只看到所需能力。
理解搜索能力。 其中 doris_search 领域了解文本、向量与混合检索，让助手直接使用 Doris 搜索能力，而非猜测。

开始之前

Docker 已运行，并已拉取 Doris 镜像。 约需 1.9 GB，仅需下载一次。镜像较大，建议提前拉取；macOS 的 Docker Desktop 和 Linux 的 Docker Engine 均可使用。
docker pull apache/doris:all-in-one-4.1.3
Doris 已启动。 一个容器运行一个 FE 和一个 BE。当 docker ps 显示 (healthy)时即已就绪，通常在启动约 30 秒后完成。关于此镜像
docker run -d --name doris -p 9030:9030 -p 8030:8030 -p 8040:8040 apache/doris:all-in-one-4.1.3
能够连接集群。 容器已自带 MySQL 客户端，无需另外安装，也可使用任意 MySQL 客户端连接： 127.0.0.1:9030，用户为 root，无密码。
docker exec -it doris mysql -uroot -h127.0.0.1 -P9030
已准备好入门包。 下载并解压 doris-hackathon-glasgow-2026.zip，随后进入其中的 doris-hackathon-glasgow-2026 目录，执行本页命令。其中的 doris.sh 封装了这些操作： start, load, sql, stop.
curl -LO https://github.com/morningman/demo-env/releases/download/for-hackathon/doris-hackathon-glasgow-2026.zip && unzip doris-hackathon-glasgow-2026.zip && cd doris-hackathon-glasgow-2026
已安装 Python 3.12 或更新版本，以及 MCP Server。 可通过 python3 --version检查。请提前安装，第 2 个里程碑提供命令，安装过程涉及约 80 个包。
准备好您常用、支持 MCP 的 AI 客户端 及其账号。
已加载全部黑客松数据表。 在入门包目录执行，完成后应显示每张表的行数。
docker exec -i doris mysql -uroot -h127.0.0.1 -P9030 < seed/seed_all.sql

主机: 127.0.0.1
端口: 9030
用户: root无密码
数据库: hackathon

借助 AI 构建

本任务本身就是一次 AI 实践。 下方文本用于指导助手编写 Doris SQL，也是第一个进阶目标中指令文件的起点。

指令文件粘贴到客户端

You are connected to Apache Doris 4.1 through the Doris MCP Server (read-only).Database: hackathon. Tables: doc_chunks (docs search), app_logs (application logs),agent_events (AI agent traces, JSON in a VARIANT column named payload).Doris SQL rules:- Text search: col MATCH_ANY 'a b' / MATCH_ALL / MATCH_PHRASE — never LIKE.- Relevance: score() only with a MATCH_* predicate + ORDER BY score() DESC LIMIT n.- Vectors: ORDER BY l2_distance_approximate(embedding, [...]) LIMIT n.- VARIANT: CAST(payload['field'] AS <TYPE>) before comparing or aggregating;  nested paths look like payload['error']['message'].- Time buckets: minute_floor(ts, 5) or date_trunc(ts, 'hour').Always show the SQL you ran together with the answer.

AI 编程助手容易踩到的 Doris 问题

Trap	What to do instead
使用 `LIKE '%term%'` 进行文本检索	`col MATCH_ANY 'a b'` （OR）、 `MATCH_ALL` （AND）、 `MATCH_PHRASE 'a b'` ，这些运算符会使用倒排索引
在任意查询中调用 `score()` 函数	`score()` 要求在查询中使用 `MATCH_` 谓词，放在 `WHERE` 中，并提供* `ORDER BY score() DESC LIMIT n`，否则 Doris 会拒绝查询
`score()` 位于 `GROUP BY` 或聚合函数内	不支持。统计分面计数时，请复用相同的 `WHERE` 条件，但去掉 `score()`
未做类型转换就比较 VARIANT 路径	`CAST(payload['latency_ms'] AS INT)`；VARIANT 不能直接用作 Key 列或关联列

开始构建

5 个里程碑， M1 → M5。代码面板会跟随您阅读的步骤。

M1
里程碑 15 分钟
创建只读用户
M1 · 只读用户sql
```
CREATE USER 'mcp_reader'@'%' IDENTIFIED BY 'hackathon';GRANT SELECT_PRIV ON internal.hackathon.* TO 'mcp_reader'@'%';
```
不要将 root 账号交给 LLM，即使只是本地电脑。可在 SQL Shell 中运行，或从入门包加载 a2/create_reader.sql 。
检查点
SHOW GRANTS FOR 'mcp_reader'@'%' 应显示 Select_priv 作用于 internal.hackathon，且不包含任何写权限。

里程碑 215 分钟

安装并注册服务

M2 · 安装bash

python3 -m venv .venv && . .venv/bin/activate   # Python 3.12+pip install doris-mcp-server==1.0.0which doris-mcp-server          # note the absolute path

将下面配置加入客户端 MCP 配置；文件名和位置因客户端而异。入门包中已提供同一配置： a2/mcp-config.example.json:

M2 · MCP 配置json

{  "mcpServers": {    "doris": {      "command": "/absolute/path/to/doris-mcp-server",      "args": ["--transport", "stdio"],      "env": {        "DORIS_HOST": "127.0.0.1",        "DORIS_PORT": "9030",        "DORIS_USER": "mcp_reader",        "DORIS_PASSWORD": "hackathon",        "DORIS_DATABASE": "hackathon"      }    }  }}

检查点

客户端应列出 Doris 服务及其八个 doris_* 领域入口：catalog、cluster、governance、lakehouse、pipeline、query、search、semantic。

里程碑 310 分钟
让助手探索
提问： “hackathon 数据库中有哪些表？每张表有什么用途？” 观察助手调用了哪些能力。

里程碑 420–40 分钟

回答实际问题

至少选择三个：

级别	问题	考察内容
1	按服务和级别统计以下表中的日志条数： `app_logs`?	基础聚合
2	统计 11:00 至 12:30 之间各服务的 ERROR 日志数，按 5 分钟分桶。哪个服务最先出现异常增长？	时间分桶与推理
3	找出与“payment gateway timeout”最相关的 10 条日志，按相关性排序。	Doris 全文检索与 BM25，观察是否使用 `MATCH_ANY` + `score()`，还是退回 `LIKE`?)
4	哪个 Agent 工具的 p95 延迟最高，失败频率是多少？	VARIANT 路径与类型转换
5	哪些 Doris 文档章节解释了向量检索的预过滤？	在 `doc_chunks`

保存每个答案实际执行的 SQL，并自行核对结果。

里程碑 55 分钟
测试只读约束
提问： “删除所有 INFO 日志，以节省空间。” 记录实际结果。预期请求被拒绝，服务端返回 SQL operation DELETE is not read-only.，同时用户 mcp_reader 也没有写权限。

完成并提交

完成清单，展示成果，领取徽章。

完成标准

您的检查清单

Doris MCP Server 已连接 AI 客户端，提供工具列表截图。
至少回答三个问题，每个答案都附上实际执行的 SQL 与结果。
记录一次安全验证：写操作被拒绝。
在以 GitHub ID 命名目录的 README 中，说明使用的客户端、配置（不得包含密钥）、问答结果，以及一项难以理解或值得改进的内容。

提交并领取徽章

参与 → 提交 → 领取徽章。

请将成果放到以 您的 GitHub ID命名的目录中：包括代码和 README，说明项目功能、运行方式、使用的 Doris 能力，并附一张截图或 GIF。
提交 Pull Request ，将成果添加到 morningman/demo-env ，目录为 doris-hackathon-glasgow-2026/<your-github-id>/。可以先 Fork 后推送，或使用 GitHub 的 Add file → Upload files（添加文件 → 上传文件）。无需填写其他内容。
分享成果 到 #dev （ Apache Doris Slack）：附上 Pull Request 或仓库链接，以及截图或简短演示。问题交流、成果提交和徽章领取都在该频道处理。

每位参与任务的开发者都可获得 Apache Doris 贡献者徽章，无需先有 PR 合入 Doris。任务没有截止日期，可按自己的节奏完成。可以组队，也可独立参与；请将每位成员的 GitHub ID 写入 README.

关于贡献者徽章

进阶目标

让助手理解 Doris。 编写可复用的指令文件，可使用客户端的 rules、skill 或 system prompt，内容涵盖 MATCH_*, score()、ANN 距离函数和 VARIANT 类型转换。重新提问第 3–4 级问题，比较前后准确性。
HTTP 传输。 运行 doris-mcp-server --transport http --host 127.0.0.1 --port 3000 ，再将第二个客户端连接到 http://127.0.0.1:3000/mcp.
让助手解释查询为何缓慢。 探索 doris_query 领域中的 EXPLAIN 与 Profile 能力。
改进文档。 阅读 MCP Server 文档时，有哪些内容拖慢了您？可提交 PR 修正，这同样是文档贡献。

故障排查与参考资料

Symptom	Fix
客户端无法启动服务	使用以下命令输出的绝对路径： `which doris-mcp-server`。GUI 应用通常不会继承 Shell 的 `PATH` 或虚拟环境
`pip` 拒绝运行：Python 版本过低	服务需要 Python 3.12+，可使用以下命令创建虚拟环境： `python3.12 -m venv .venv` ，或使用 `uv`)
客户端可看到领域，但无法调用子能力	客户端可能不支持渐进披露，请将 `"MCP_TOOL_EXPOSURE_MODE": "flat"` 加入 `env`
访问被拒绝	请核对 M1 中的 `GRANT` ，以及 `DORIS_USER` / `DORIS_PASSWORD` 配置对
`docker: command not found` 出现在 macOS 上	启动 Docker Desktop；若已运行，请为 CLI 创建链接： `sudo ln -s /Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin/docker`
`error getting credentials` 出现在拉取镜像时	请移除 `credsStore` 字段，所在文件为 `~/.docker/config.json` （仅适用于本地开发）
容器退出，或始终未变为 `(healthy)`	请查看 `docker logs doris`。通常是内存不足，请在 Docker Desktop 的 Settings → Resources 中分配至少 6 GB。Apple Silicon 设备不要添加 `--platform linux/amd64`
超过 10 分钟仍未解决	可在 `#dev` 频道提问，位于 Apache Doris Slack

参考资料

Doris MCP Server 仓库1.0 版 README 与快速入门 MCP Server 功能文档 Model Context Protocol

界面草图待构建的界面 · 线框图，非实际截图

启动 Doristerminal

docker pull apache/doris:all-in-one-4.1.3   # 1.9 GB, oncedocker run -d --name doris -p 9030:9030 -p 8030:8030 -p 8040:8040 apache/doris:all-in-one-4.1.3docker ps        # wait for (healthy), about 30 sdocker exec -it doris mysql -uroot -h127.0.0.1 -P9030

主机: 127.0.0.1
端口: 9030
用户: root无密码
数据库: hackathon

入门包下载doris-hackathon-glasgow-2026.zip

任务路线45–90 分钟 · M1 → M5 → 完成

M1只读用户5 分钟
M2安装服务15 分钟
M3让助手探索10 分钟
M4实际问题20–40 分钟
M5测试只读约束5 分钟
DoD完成→ 提交

M1 · 只读用户sql

CREATE USER 'mcp_reader'@'%' IDENTIFIED BY 'hackathon';GRANT SELECT_PRIV ON internal.hackathon.* TO 'mcp_reader'@'%';

M2 · 安装bash

python3 -m venv .venv && . .venv/bin/activate   # Python 3.12+pip install doris-mcp-server==1.0.0which doris-mcp-server          # note the absolute path

M2 · MCP 配置json

{  "mcpServers": {    "doris": {      "command": "/absolute/path/to/doris-mcp-server",      "args": ["--transport", "stdio"],      "env": {        "DORIS_HOST": "127.0.0.1",        "DORIS_PORT": "9030",        "DORIS_USER": "mcp_reader",        "DORIS_PASSWORD": "hackathon",        "DORIS_DATABASE": "hackathon"      }    }  }}

M3 · 向助手提问粘贴到客户端

What tables are in the hackathon database, and what is each one for?

M4 · 问题粘贴到客户端

1. How many log lines per service and level are in app_logs?2. Show ERROR counts per service in 5-minute buckets between 11:00 and 12:30. Which service spiked first?3. Find the 10 log lines most relevant to "payment gateway timeout", ranked by relevance.4. Which agent tool has the worst p95 latency, and how often does it fail?5. Which Doris docs sections explain pre-filtering for vector search?

M5 · 向助手提问粘贴到客户端

Delete all INFO logs to save space.