Python 查询脚本

Python 查询脚本是与 SQL、DQL 并列的第三种查询脚本类型。它让你用真正的 Python 语法与标准库编写数据处理逻辑：既能像 SQL 一样从数据源取数，也能用 Polars 风格的 DataFrame 做转换、聚合、清洗，还能通过 fetch() 发起 HTTP 请求拉取外部数据。

与查询编辑器中的其它模式一样，Python 脚本走同一套执行流程——选择数据源、编写脚本、运行、查看结果、可视化。

备注

DQL 基于 Starlark（一种类 Python 语言，但并非真正的 Python）。Python 查询脚本运行的是真正的 Python（由 RustPython 解释器编译为 WebAssembly，在沙箱中执行），因此可以 import 标准库、使用完整的 Python 语法。数据处理 API 采用 Polars 风格（pl.col、select/with_columns/filter/group_by().agg() 与惰性表达式）。

快速上手

Python 脚本必须定义一个 main() 函数作为入口，main() 的返回值就是查询结果：

def main():
    return [{"city": "北京", "value": 1}, {"city": "上海", "value": 2}]

main() 可以返回：

DataFrame — 直接转换为结果集（推荐，零 JSON 往返）
Series — 转换为单列结果集
list[dict] 或其它 JSON 可序列化的值 — 走 JSON 转换路径

无需任何 import：DataFrame、Series、pl 以及下面的 query、fetch、args、print 都已直接注入脚本作用域。

从数据源取数

用内置的 query() 执行 SQL，返回一个 DataFrame：

def main():
    df = query("SELECT id, name, amount FROM orders WHERE amount > ?", 100)
    return df.filter(pl.col("amount") > 500)

query() 走的是与普通 SQL 查询相同的查询引擎通路，支持已绑定/挂载的多个数据源与跨源查询。

注意

SQL 查询返回的 timestamp / date 列会以字符串形式回来，需要显式转换：

df = df.with_columns(pl.col("created_at").str.to_datetime())

使用参数

调用方传入的参数通过全局 args（始终是一个 dict）读取：

def main():
    threshold = args["threshold"]
    df = query("SELECT * FROM sales")
    return df.filter(pl.col("revenue") > threshold)

发起 HTTP 请求

内置 fetch() 提供 JS fetch 风格的 HTTP 能力：

def main():
    res = fetch("https://api.example.com/data", headers={"Authorization": "Bearer ..."})
    if not res.ok:
        return [{"error": res.status}]
    return res.json()

body 为 dict / list 时会自动 JSON 序列化，并默认带上 content-type: application/json
传输层错误（如 DNS/连接失败）会抛出异常；HTTP 4xx/5xx 不抛异常，通过 res.ok / res.status 判断
res.text() 取原始文本、res.json() 解析 JSON、res.headers.get(name) 读响应头

处理数据（Polars 风格）

DataFrame / Series / 惰性 Expr 提供选择、过滤、派生列、分组聚合等操作。此外还支持滚动窗口、指数加权移动、时间窗口分组、Join、条件表达式、累计求和等高级数据处理能力：

def main():
    df = query("SELECT category, region, amount FROM sales")
    return (
        df.filter(pl.col("amount").is_not_null())
          .group_by("category", "region")
          .agg(pl.col("amount").sum().alias("total"))
    )

完整 API 见 Python 语言参考。

打印日志

内置 print() 被重定向到脚本日志（不会污染结果集），便于调试：

def main():
    df = query("SELECT * FROM orders")
    print("行数:", df.height)
    return df

沙箱与限制

Python 脚本在受限的 WebAssembly 沙箱中执行，请注意以下边界：

限制	说明
入口函数	必须定义可调用的 `main()`，否则报错
执行超时	单次执行最长 60 秒
内存上限	约 256 MiB 线性内存
无文件系统	脚本不能读写本地文件
结果截断	结果超过一定行数会被截断

标准库方面，冻结的纯 Python 标准库（如 json、re、argparse）以及 math、datetime、struct、hashlib 等原生模块均可正常 import。

快速上手​

从数据源取数​

使用参数​

发起 HTTP 请求​

处理数据（Polars 风格）​

打印日志​

沙箱与限制​

相关文档​