AB
AB
AiBoss

All Categories

Tutorials

CodeFuse

Tutorials

用 CodeFuse-Query 的 Jupyter Notebook 教程跑通 Godel 查询

CodeFuse-Query 提供了一套以 Jupyter Notebook 形式组织的教程，配合项目预置的开发容器即可直接运行 Godel 查询脚本。本文说明两种进入方式（GitHub Codespaces 远程加载、本地 VS Code 开发容器），并逐条讲解 Godel Kernel 的 %db、%%save_to、%%python 等用法，最后给出一个从设置数据库路径到导出 JSON、再用 pandas 排序取前十的完整示例。

CodeFuse-Query 是一套面向代码的查询与分析工具，它用一门叫 Godel 的脚本语言描述你想从代码库里提取什么信息。为了让人不必先啃完文档就能上手，项目把教程做成了 Jupyter Notebook 的形式，并配好了开发容器（devcontainer）：打开就能读、能改、能跑，边看边执行，立刻看到查询结果。这篇教程面向第一次接触 CodeFuse-Query、想先跑通一条查询链路再决定是否深入的人。如果你更习惯在浏览器里直接打开工具页面对照参数，可以先看 CodeFuse 这一条目，再回到本文按步骤操作。

整篇内容围绕两件事展开：一是把运行环境弄起来，二是把 Godel Kernel 的几个交互命令用熟。环境部分有两条路——用 GitHub Codespaces 在浏览器里远程加载，或者用本地 VS Code 加 Docker 起一个开发容器；两条路最终都落到同一个目录、同一个 Notebook 文件上。命令部分则覆盖设置 COREF 数据库路径、执行 Godel 脚本、把结果存成 JSON、以及在同一个 Notebook 里切到 Python 做后续处理。最后给一个从头到尾能跑通的最小例子。

准备工作

先明确你选哪条路，因为两条路的前置条件完全不同。

路线一：GitHub Codespaces（浏览器内运行）

这条路不需要在本地安装任何东西，也不需要额外配置开发环境。你只需要一个能访问 GitHub 并创建 Codespace 的账号。Codespace 的可用额度、机型与计费方式由 GitHub 侧的账户策略决定，具体以 GitHub 当前页面显示的信息为准。

适合的场景：临时想试一下、手边机器没装 Docker、或者只是想快速翻一遍教程内容。

路线二：本地 VS Code 开发容器

这条路需要在本机准备三样东西：

  • VS Code：本地安装，版本要求以 VS Code 官方当前说明为准。
  • Docker：本地安装并处于运行状态，开发容器依赖它来构建和启动。
  • Dev Containers 扩展：扩展 ID 为 ms-vscode-remote.remote-containers。如果你装的是 Remote Development 扩展包（扩展 ID ms-vscode-remote.vscode-remote-extensionpack），它已经包含了 Dev Containers 扩展，不必重复安装。

扩展没装的话，在 VS Code 的扩展商店里用上面的扩展 ID 搜索并安装即可。这一步必须在打开项目、触发容器提示之前完成，否则 VS Code 不会给出「用开发容器重新打开」的选项。

适合的场景：需要反复调试、希望改动落在本地、或者网络条件不适合长时间挂着远程 Codespace。

两条路共用的东西

无论走哪条路，最终你面对的都是项目仓库里的同一套文件：

  • .devcontainer/devcontainer.json：开发容器配置文件，VS Code 靠它识别这是一个 devcontainer 项目。
  • tutorial/notebook 目录：教程 Notebook 所在位置。
  • examples 子目录下的 .ipynb 文件：真正要打开的那个 Jupyter Notebook 教程。

另外，Godel Kernel 在执行查询时会调用 CodeFuse-Query 的命令行工具 sparrow（通过 sparrow query run 子命令）。在开发容器镜像里这个 CLI 已经就位，所以正常情况下你不需要单独安装它；但如果你在容器外自己搭环境，就需要确认它存在，检查方法见下一节。

操作步骤

第一步：用 GitHub Codespaces 打开教程

  1. 进入项目主页，点击 Code 按钮，切到 Codespaces 标签页。
  2. 在当前分支上创建一个 Codespace。
  3. 等待创建完成后，打开这个 Codespace。
  4. 加载完毕后，在文件树里进入项目的 tutorial/notebook 目录。
  5. 在 examples 下选中那个 Jupyter Notebook 教程文件，也就是 .ipynb 文件。
  6. 右上角会弹出「Select Kernel」选择框，先选 Jupyter Kernel...，再选 Godel Kernel。
  7. 内核选定后即可开始逐格执行。

第 6 步是关键。如果内核选错，Notebook 里的 Godel 脚本会被当成普通文本或按其他语言解释，执行结果不会是你要的查询输出。看到 Godel Kernel 这个选项，说明开发容器里的内核已经注册好了。

第二步：用本地 VS Code 开发容器打开教程

  1. 把代码克隆到本地，用 VS Code 打开这个项目。
  2. VS Code 会自动检测到 .devcontainer/devcontainer.json 这个配置文件。
  3. 它会提示你是否用开发容器配置重新打开仓库，点击 Reopen（重新打开）。
  4. 容器加载完成后，切到项目的 tutorial/notebook 目录。
  5. 在 examples 下选中 Jupyter Notebook 教程文件，开始体验。

如果第 3 步没有出现提示，先回头确认 Dev Containers 扩展是否装好、Docker 是否在运行。这两者任一缺失，VS Code 都不会走到「重新打开」这一步。

第三步：认识 Godel Kernel 能做什么

Godel Kernel 是 CodeFuse-Query 为 Jupyter 提供的专用内核，作用是把 CodeFuse-Query 的交互能力搬进 Notebook 环境。它提供四类能力：

  • 在 Jupyter Notebook 里编写并执行 Godel 脚本。
  • 支持 %%python 命令，在同一个 Notebook 里写 Python 代码，便于对查询出来的数据做进一步的可视化和后处理。
  • 支持自定义 COREF 数据库路径。
  • 把某个 Jupyter 单元格的输出转储到指定文件。

这四点基本覆盖了日常使用：查询、后处理、换数据源、落盘。

第四步：设置要查询的 COREF 数据库

查询之前必须先告诉内核去哪个数据库上跑。用 %db 命令指定路径：

%db /path/to/db

教程里常用的相对路径写法是：

%db ./db

内核会读取这个值，后续的查询都基于它。也就是说，一个 Notebook 里换一次 %db，后面的查询就换到另一个库上，不需要重启内核。

顺带一提，Notebook 单元格里可以用 ! 前缀执行 bash 命令。一个实用的检查是确认 sparrow 这个 CLI 是否存在：

!which sparrow

如果这条命令有输出，说明 CLI 在 PATH 里，查询链路的下半段是通的；如果没有任何输出，说明当前环境里找不到 sparrow，后面的 Godel 查询会失败。

第五步：编写并运行 Godel 查询

数据库路径设好之后，直接在单元格里写 Godel 脚本即可。内核的处理方式是：为当前要运行的 Godel 脚本创建一个临时文件，然后调用 sparrow query run 执行查询，结果以 HTML 形式展示在 Notebook 里。

一个最简的单元格长这样：

// Write your query and run in the notebook
// ...

%db 也可以写在 Godel 脚本的第一行，和查询放在同一个单元格里：

%db ./db
// Write your query and run in the notebook
// ...

两种写法效果一致：单独一个单元格设库、查询单元格只写查询；或者每个查询单元格自带 %db 行。后者在需要频繁切换数据库的 Notebook 里更省事，前者在整篇只用一个库时更干净。

结果以 HTML 渲染，意味着表格类输出可以直接在 Notebook 里阅读，不需要额外格式化。

第六步：把查询结果保存成 JSON

想在 Python 里继续处理查询结果，就得先把它落盘。用单元格命令 %%save_to 把最近一次成功运行的查询结果保存为 JSON 文件：

%%save_to ./query.json

注意两点：一是它保存的是「上一次成功运行」的结果，所以要先跑查询、再跑保存；二是它写在单元格开头，作为单元格级命令使用。

第七步：在同一个 Notebook 里跑 Python

Python 代码可以用 %%python 或 %python 运行。典型用法是把上一步导出的 JSON 读进来，排序、取前若干条：

%%python
import pandas as pd

data = pd.read_json('./query.json')
data.sort_values('cmplx', ascending=False, inplace=True)
top_10 = data.head(10)
print(top_10)

单行或短片段也可以用 %python：

%python
print('hello')

这样一条链路就完整了：Godel 查询负责从代码库里取数据，JSON 负责把数据交出去，Python 负责排序、筛选和可视化。

一个完整示例

下面把前面的步骤串成一个从头到尾能跑通的最小流程。假设你已经通过 Codespaces 或本地开发容器打开了教程 Notebook，并且内核已选为 Godel Kernel。

第 1 格：确认环境

!which sparrow

有输出即说明 CLI 可用，可以继续。

第 2 格：指定数据库

%db ./db

把查询目标指向当前目录下的 db。如果你的数据库在别处，换成实际路径。

第 3 格：执行 Godel 查询

%db ./db
// Write your query and run in the notebook
// ...

运行后，结果以 HTML 表格形式显示在单元格下方。这一格成功执行，是下一步保存的前提。

第 4 格：导出结果

%%save_to ./query.json

执行后，上一次成功查询的结果被写入当前目录的 query.json。

第 5 格：用 Python 处理

%%python
import pandas as pd

data = pd.read_json('./query.json')
data.sort_values('cmplx', ascending=False, inplace=True)
top_10 = data.head(10)
print(top_10)

这一格按 cmplx 字段降序排列，取前 10 条打印出来。到这里，你已经走完了「设库 → 查询 → 落盘 → 后处理」的完整闭环。后续想换查询，只需要改第 3 格的 Godel 脚本，第 4、5 格可以原样复用。

注意事项

  • 内核必须选对。 打开 Notebook 后如果右上角没有选到 Godel Kernel，Godel 脚本不会按预期执行。选择路径是「Select Kernel」→「Jupyter Kernel...」→「Godel Kernel」。
  • 本地路线的前置扩展不能漏。 没有 Dev Containers 扩展（ms-vscode-remote.remote-containers）或包含它的 Remote Development 扩展包，VS Code 不会提示用开发容器重新打开项目。
  • Docker 必须处于运行状态。 本地开发容器依赖 Docker 构建与启动，Docker 没起来时容器加载会失败。
  • %%save_to 依赖上一次成功运行。 它保存的是最近一次成功执行的查询结果，所以顺序不能颠倒：先跑查询，再保存。查询失败时保存出来的内容不是你想要的数据。
  • %db 是查询的前提。 没有设置数据库路径就执行 Godel 脚本，内核没有可用的库去查询。相对路径 ./db 是相对于当前工作目录的，换目录后要相应调整。
  • 查询依赖 sparrow CLI。 内核通过调用 sparrow query run 执行查询。在预置的开发容器里它已经存在；自行搭建环境时需要确认它在 PATH 中，可用 !which sparrow 检查。
  • Codespaces 的额度与计费以 GitHub 当前信息为准。 远程加载不需要本地配置，但可用时长、机型等受账户策略约束，长期使用前先确认自己的额度情况。
  • 教程内容与工具能力可能随版本变化。 命令语法、内核支持的功能、示例脚本的具体写法，均以项目当前版本与官网当前信息为准。
Back