datadata-dql

name	datadata-dql
description	为 Datadata 平台编写 DQL 数据处理脚本 — 基于 Starlark 的扩展脚本语言，支持 DataFrame/Series 操作、SQL 查询、HTTP 请求等。当用户需要编写数据转换、数据清洗、数据生成或自定义数据处理逻辑时使用此 skill。

Datadata Query Language (DQL) 脚本编写

DQL 是基于 Starlark 的自定义脚本语言，扩展了 Starlark 的语法和标准库，提供数据处理、HTTP 网络调用等能力。

🔴 核心规则

1. 脚本必须有 return 语句

DQL 脚本实际是一个函数的 body，最后必须有 return 语句返回数据，否则执行结果为空。

# ✅ 正确
df = query("SELECT * FROM users")
return df

# ❌ 错误：没有 return，结果为空
df = query("SELECT * FROM users")

2. 必须先阅读对应的 References 文档

禁止仅凭本文档就编写 DQL 代码。 本文档只是索引，实际 API 签名、参数、返回值以 references 为准。编写代码前至少阅读以下对应文档：

场景	必读文档
SQL 查询	query.md
HTTP 请求	fetch.md
数据转换 / DataFrame	dataframe.md
Series 操作	series.md
时间处理 / 数学 / JSON	time.md、math.md、json.md
concat / throw / print	builtins.md
2D 绘图	canvas_drawing.md

3. 关于 API 文档的权威来源

所有函数/类的完整签名定义以 builtins.pyi 为准，各 .md 文件仅为快速参考和示例说明。

4. 所有 DQL 扩展均为内置全局名称

query、fetch、concat、throw、json、math、time、canvas、DataFrame、Series 都是内置的全局名称，无需 import。

5. 不确定时先问用户，不要自行猜测

当遇到以下情况时，必须先向用户确认，而不是自行假设：

• 外部 API 返回的数据结构或字段含义不明确
• 用户需求中的业务逻辑模糊（如：什么是"异常"、阈值是多少）
• 数据字段顺序不确定（如 K 线的 [开, 高, 低, 收] 还是 [开, 收, 低, 高]）
• 用户提到的表名、列名在上下文中不存在或不确定

# ❌ 错误：自行猜测字段顺序，导致结果错误
data = resp.body["klines"]
df = DataFrame(data, columns=["time", "open", "high", "low", "close"])  # 猜错了

# ✅ 正确：先输出类型和数据给用户确认
return {"type": type(resp.body), "data": resp.body}  # 让用户确认类型和数据结构
# 然后根据用户反馈再写处理逻辑

工作流程

1. 理解用户需求 — 确定脚本的目标（数据转换、数据清洗、数据生成、可视化、HTTP 调用等）
2. 查询数据 — 使用 query() 或 fetch() 获取数据
3. 先验证数据再处理 — 用 return 临时返回原始数据确认结构，不要凭猜测写代码
4. 数据处理 — 使用 Series/DataFrame 的方法进行数据操作（过滤、转换、聚合等）
5. 生成结果 — 返回处理后的数据或结果对象
6. 逐步验证 — 每步操作后及时 return 临时返回中间结果来检查，确认后再继续

核心概念

• DataFrame：二维表格，可访问列 (df['col'])、行 (df[0])，支持分组、排序、合并等操作
• Series：一维列数据，支持映射 (.map())、过滤、统计聚合等
• Timestamp：时间戳类型，用于时间序列的滚动窗口和重采样（详见 time.md）
• DType：数据类型包括 int, float, string, date, timestamp 等

模块和函数速查

以下均为内置全局名称，无需 import，直接使用：

名称	用途	详见
query(sql, ...)	SQL 查询	query.md
fetch(url, ...)	HTTP 请求	fetch.md
DataFrame()	二维表格	dataframe.md
Series()	一维列	series.md
math.ceil(x) 等	数学函数	math.md
time.time() 等	时间处理	time.md
json.dumps(x) 等	JSON 处理	json.md
concat([df1, df2])	连接数据	builtins.md
throw(err)	抛出错误	builtins.md
print(...) 等	内置函数	builtins.md
canvas.Context(w,h)	2D 绘图	canvas_drawing.md

使用场景

各模块参考文档中均包含实用示例：

• 数据清洗、聚合、合并、异常检测、RFM 分析 → dataframe.md
• 月度对比、每日活跃用户 → query.md
• 外部 API 集成、发送数据到外部服务 → fetch.md
• 时间处理与时间戳 → time.md
• JSON 序列化与格式化 → json.md
• 数学计算 → math.md
• 错误处理与数据验证 → builtins.md
• Canvas 基础图形绘制 → canvas_drawing.md
• 调试技巧、性能优化、常见陷阱 → faq_best_practices.md（脚本出错或性能不佳时查阅）

输出规则

• 脚本最后必须有 return 语句，DQL 脚本是函数的 body，无 return 则结果为空
• 可返回 DataFrame、dict、list 或其他可序列化的数据结构
• 返回值会自动转换为 JSON 并发送给前端
• 避免返回过大的数据结构（> 1MB），必要时加入 LIMIT 限制

Starlark 基础

DQL 基于 Starlark（Python 风格），支持：

# 基本类型
x = 42                      # 整数
s = "hello"                 # 字符串
lst = [1, 2, 3]            # 列表
d = {"key": "value"}        # 字典

# 控制流
if x > 0:
    print("positive")
for i in range(5):
    print(i)

# 函数和 Lambda
def add(a, b):
    return a + b
square = lambda x: x * x

详见 Starlark 官方文档。

Starlark 与 Python 的关键差异

以下是 Starlark 不支持的 Python 特性，编写 DQL 脚本时务必避免：

❌ 不支持	替代方案
import 语句	所有 DQL 扩展为内置全局名称，直接使用
isinstance(x, T)	❌ **不支持，**使用 x == None 或检查具体字段
try / except	❌ **不支持，**使用 throw() 提前终止，或返回错误信息
type(x)	返回类型名称字符串（如 "int"）
set() / {} 集合	使用 dict 或 list 替代
class 定义	Starlark 不支持自定义类
global / nonlocal	不支持
generator / yield	不支持
open() / 文件 I/O	使用 query() 和 fetch()

References

本 skill 包含以下参考文档：

文档	说明
dataframe.md	DataFrame 完整 API 参考
series.md	Series 完整 API 参考
query.md	SQL 查询（query）参考
fetch.md	HTTP 请求（fetch）参考
math.md	数学函数（math）参考
time.md	时间处理（time）参考
json.md	JSON 处理（json）参考
builtins.md	内置函数（concat, throw, print 等）参考
canvas_drawing.md	Canvas 2D 绘图 API + 示例

外部资源

• 完整 API 签名：builtins.pyi — 所有类型提示（权威来源）
• Starlark 语言：https://github.com/bazelbuild/starlark/blob/master/spec.md — 官方 Starlark 语言规范