datadata-pythonlisted
Install: claude install-skill datadata-team/datadata-skills
# Datadata Python 查询脚本编写
Python 查询脚本是 Datadata 平台与 SQL、DQL 并列的第三种查询脚本类型。它运行**真正的 Python**（RustPython 编译为 WebAssembly，在沙箱中执行），提供 **Polars 风格**的 `DataFrame` / `Series` / `Expr` 数据处理 API，并内置 SQL 取数（`query()`）与 HTTP 请求（`fetch()`）能力。
## 🔴 核心规则
### 1. 脚本必须定义 `main()` 函数
Python 脚本**必须定义一个可调用的 `main()` 函数**作为入口，`main()` 的返回值即查询结果。没有 `main()` 会直接报错。
```python
# ✅ 正确
def main():
df = query("SELECT * FROM users")
return df
# ❌ 错误：没有 main()，无法执行
df = query("SELECT * FROM users")
```
`main()` 可返回以下形态之一：
- `DataFrame` — 直接转换为结果集（推荐）
- `Series` — 转换为单列结果集
- `list[dict]` — 每个 dict 是一行
- `dict[str, list]` — **列式**，键是列名、值是等长的列表
> 若要返回若干标量汇总值，**包成单行 `list[dict]`**（如 `return [{'total': total, 'count': n}]`），因为顶层 dict 仅支持 `dict[str, list]` 列式形态。
### 2. 编写前必须先阅读对应的 References 文档
**禁止仅凭本文档就编写代码。** 本文档只是索引，实际 API 签名、参数、返回值以 references 为准。
| 场景 | 必读文档 |
| --- | --- |
| SQL 取数 / HTTP 请求 / 参数 / 日志 | [builtins.md](./references/builtins.md) |
| 数据转换 / DataFrame | [dataframe.md](./references/dataframe.md) |
| Series 操作 | [series.md](./references/series.md) |
| 表达式 / 列运算 / 字符串 / 日期时间 | [expr.md](./references/expr.md) |
| 完整可运行示例 | [examples.md](./references/examples.md) |
### 3. API 签名的权威来源
所有函数 / 类的完整签名以 [`__builtins__.pyi`](./references/__builtins__.pyi) 为准，各 `.md` 文件仅为快速参考和示例说明。**严格按 `.pyi` 中声明的方法编写**——数据处理 API 是 Polars 风格，但只实现了 `.pyi` 中列出的子集。
### 4. 注入的全局名称，无需 `import`
`query`、`fetch`、`args`、`print`、`pl`、`DataFrame`、`Series` **都是注入到脚本作用域的全局名称，无需 `import`**。
标准库需要时可正常 `import`：