datadata-manual

name	datadata-manual
description	本技能包含对 Datadata 平台的详细操作手册，在使用 Datadata 平台相关功能时，**必须先加载本技能**。 Datadata 平台功能包括: 1. 数据源管理 - 搜索、查询、元数据增强 2. 执行 Query 查询 - 对数据源执行 SQL、DQL 查询，并获取结果 3. Data Spaces 数据空间管理 - 创建数据空间、通过 SQL 管理表结构与数据

功能概览

本 skill 通过 Datadata MCP Server 直接调用平台能力，在使用之前，请先确认已经连接 Datadata MCP Server。

生成独立 Python 脚本（爬虫/ETL/批处理）请使用 datadata-rest-api skill。 MCP 专为聊天交互设计，不适用于生成独立运行的脚本文件。

覆盖能力

• 搜索数据源 — 支持用户名/关键词搜索公开和私有数据源
• 元数据查询 — 检查数据源信息、列出表、描述列结构
• 元数据增强 — 设置表注释和列注释，提升数据可理解性
• 创建 Data Space — dataspace-create 创建数据空间数据源
• Data Space SQL 执行 — dataspace-execute-sql 在单一数据空间内运行任意 DuckDB SQL（建表/写入/改表/删表等 DDL/DML）
• Schema 扫描 — 触发异步扫描，刷新数据源表元数据
• 执行 SQL 查询 — 通过 execute-adhoc 执行 SELECT 查询（只读），返回执行 ID 和结果下载链接
• DQL 脚本执行 — 支持 DQL（Starlark）脚本类型

使用场景

场景	示例
查询 Datadata 中的数据	"帮我查一下销售数据"、"统计上个月的用户增长"
搜索数据源	"搜索名叫 customers 的数据源"、"看看我有哪些数据源"
探索数据源结构	"看看这个 datasource 有哪些表"、"描述一下 customers 表的字段"
设置表和列的注释	"给 users 表加个注释"、"把 email 列的注释设为'用户邮箱'"
跨数据源关联分析	"把 MySQL 的订单表和 CSV 的用户信息 join 一下"
Data Spaces 数据写入	"把爬虫结果存到 data space 里"、"批量插入这些数据"
获取查询结果	"下载上次查询的结果"
定时任务	"每天早上 8 点帮我查一下销售数据"

MCP 工具速查

以下工具由 Datadata MCP Server（https://www.datadata.com/api/mcp/v1）提供，Agent 直接调用即可：

工具	用途	关键参数
search-datasource	搜索数据源	search — 用户名或关键词
get-datasource-info	获取数据源元信息	datasourceId
list-tables	列出表和视图	datasourceId, schemaName（可选）
describe-table	获取表列结构（缓存，含注释）	datasourceId, schemaName, tableName
scan-datasource	触发 Schema 扫描	datasourceId
set-table-comment	设置表/列注释	datasourceId, schemaName, tableName, tableComment（可选）, columnComments（可选）
dataspace-create	创建数据空间数据源	name, displayName, description, visibility（public/private）, tags（可选）
dataspace-execute-sql	在数据空间内执行 SQL（写）	datasourceId, sql（DuckDB SQL，建表/写入/改表/删表）, args（可选，占位符参数）
execute-adhoc	执行 SQL/DQL 查询（只读）	name, script, scriptType（sql/dql）, queryEngine（duckdb/clickhouse）, datasources, parameters（可选）

概念

• Datasource — 查询目标的数据源。不同类型的 datasource（dataspace、MySQL、ClickHouse、CSV 等）有不同的表命名约定。
• Data space — dataspace 类型数据源（旧类型名 ducklake 已废弃），基于 DuckDB 文件存储，可建表、写数据。
• 读 / 写分离 — 查询/读取任何数据用 execute-adhoc（查询引擎，把 dataspace 作为只读数据源挂载）；修改某个 dataspace 内的表结构或数据用 dataspace-execute-sql（单一 dataspace，同步执行）。两者用途完全不同，勿混淆。
• Query（execute-adhoc） — 只读抽象，包含 SQL/DQL 脚本、datasource 绑定和查询引擎类型。每次调用创建一个 execution 并返回 executionId。
• Execution — 查询的后台执行实例。执行完成后通过返回的下载链接获取 NDJSON/CSV 结果。（dataspace-execute-sql 是同步的，无 execution，结果直接返回。）

工作流

基础查询流程

搜索数据源 → 用户确认 → 获取元信息 → （可选）列出表/描述列 → 生成查询脚本 → 执行查询 → 下载结果

每一步完成后立即停止，等待用户明确指令后再进行下一步。详见下方 规则 章节。

Data Spaces 操作

dataspace-create（创建数据空间）
  → dataspace-execute-sql（CREATE TABLE / INSERT 建表写数据）
  → execute-adhoc（挂载 dataspace 查询验证数据）
  → dataspace-execute-sql（DROP TABLE 清理）

建表/写入/改表/删表全部通过 dataspace-execute-sql 执行任意 DuckDB SQL 完成；查询走 execute-adhoc。仅限 dataspace 类型数据源。详见 Data Spaces 指南。

DQL 脚本

如需编写 DQL（Starlark）数据处理脚本，请安装 datadata-dql skill。 execute-adhoc 的 scriptType 设为 dql 即可在 MCP 中执行 DQL 脚本， 脚本编写规范和 API 参考以 datadata-dql skill 为准。

规则

🔴 搜索数据源：必须让用户确认，禁止自动选用

search-datasource 返回的结果绝不能由 Agent 自动选取。选错数据源可能导致查询错误数据等严重后果。

正确流程：

1. 调用 search-datasource 获取结果
2. 将结果以序号 + 关键信息（name、displayName、username、visibility）列表呈现
3. 等待用户明确选择序号后再使用对应的 id 进行后续操作

即使搜索结果只有 1 条，也应让用户确认。

🔴 最小操作原则：完成一步即停，禁止猜测意图

Agent 只执行用户明确要求的操作，完成当前步骤后立即停止。禁止根据上一步结果自动推断下一步。

典型违规：

• 用户："用 customers 数据源" → Agent 确认后又自动 list-tables、describe-table
• 用户："看看有哪些表" → Agent list-tables 后又自动 describe 所有表

🔴 execute-adhoc 仅限 SELECT

execute-adhoc 只支持 SELECT（只读查询引擎，dataspace 以只读方式挂载），禁止 INSERT/UPDATE/DELETE/DDL。数据写入和表管理请使用 dataspace-execute-sql。

查询结果处理

execute-adhoc 返回执行 ID 和结果下载链接（NDJSON/CSV）。Agent 应自动下载到本地再按需预览，绝不能将完整数据直接读入上下文。

流程：

1. 调用 execute-adhoc，从返回的文本消息中提取下载链接
2. Agent 用 curl 将结果下载到 /tmp/datadata-<executionId>.ndjson（或 .csv）
3. 报告：outputPath、行数（wc -l）、格式
4. 用 head/tail 预览前几行，展示数据概览
5. 用户要求时才读取完整内容或做进一步分析
6. 大数据集优先用 grep、awk、jq 等命令行工具本地处理

注意：下载链接从 execute-adhoc 返回的文本消息中直接提取，不要自行拼接 URL。

SQL 编写规范

SQL 编写前必须先通过 get-datasource-info 了解数据源类型，不同类型的表命名规则不同。完整的查询引擎、表命名、标识符引用等规范见 查询指南。

错误处理

• 任何 404：立即停止。检查 datasource ID 或 execution ID 是否正确
• 403 permission denied：正常的权限拒绝（如操作他人数据源），向用户说明权限不足
• 查询超时或失败：报告 executionId，建议调整查询或稍后重试

常见问题

Q: MCP server 连不上怎么办？

Datadata MCP Server 首选 OAuth 自动授权（无需手动申请 Key）。 如当前 Agent 不支持 OAuth，可参考 API Key 申请指南 通过 Device Flow 自动申请。 如已配置 Key 则检查 MCP server 状态或重启 Agent。

Q: 查询返回了大量数据怎么办？

不要直接读入上下文。使用返回的下载链接，配合 curl + head/tail/jq 等命令行工具在终端中处理。

Q: 需要写数据（Data Spaces）怎么办？

用 dataspace-execute-sql 执行任意 DuckDB SQL：CREATE TABLE 建表、INSERT/UPDATE/DELETE 改数据、DROP TABLE 删表。需要新建数据空间时先用 dataspace-create。写完后如改了 schema，可调 scan-datasource 刷新元数据。

References

文档	说明
./references/query-guide.md	查询引擎、表命名、标识符引用、安全性等完整规范
./references/data-spaces.md	Dataspace 创建与 SQL 执行（建表/写入/删表）
./references/api-key-setup.md	API Key Device Flow 自动申请指南

相关 skill（可选安装）

本 skill 可独立使用，以下 skill 提供互补能力：

• datadata-rest-api — 生成独立 Python 脚本（爬虫/ETL/批处理），含 REST API 参考
• datadata-dql — DQL（Starlark）脚本编写，含 DataFrame/Series API 参考