通过 icp CLI 查询 OQL canister：读…

当需要从暴露 OQL 接口（schema() + execute()）的 canister 中读取数据时，用 icp CLI 查询并解析结果。

适用场景

解决思路

1. 用 `icp canister call backend schema '()' --query` 获取 schema，并在会话内缓存（仅在部署之间变化）。
2. 解析 schema：`name` 作为查询的 `start`；`primaryKey` 标识行；`fields` 中 `role` 为 `"payload"` 是普通字段、`{"edge": {"to": "<entity>"}}` 是外键；`values` 给出字段可取的精确字面量；`typeName` 决定 JSON 字面量类型（Nat/Int/Float/Bool/Text，Principal 报为 Text）；字段名可能带 `__1`、`__2` 后缀，必须用 schema 报告的确切名字。
3. 把请求映射到实体：选持有答案的实体，用 `typeName` 和 `values` 选字面量类型，用 `role: {"edge": ...}` 看实体如何连接。
4. 把请求翻译成一个或多个查询：从想要行的实体开始，加 `where`、`orderBy`/`limit`/`offset`、`select`、`aggregate`/`groupBy`；前向边用点路径单查询跨越，反向一对多用先取父键再 `in` 的两步查询。
5. 用 `icp canister call backend execute '("<json-query>")' --query` 执行查询：JSON 作为 Candid text 字面量嵌入，外层包 `("...")`，每个 `"` 转义为 `\"`；例如 `{"start":"customer","limit":3}` 写成 `'("{\"start\":\"customer\",\"limit\":3}")'`。
6. 解析返回的 Candid 结果：外层 `rows = vec { ... }` 是行列表，内层 `vec { ... }` 是一行，每个 `record { name : text; value : Value }` 是一个单元格；按 `name` 查找单元格而非位置；`35_000 : nat` 的下划线是数字分隔符，解析时去掉；`hasMore = false` 表示取全，`true` 表示被截断需翻页。
7. 用 `where` 谓词过滤：谓词是恰好一个键的 JSON 对象，支持 `eq`/`ne`/`lt`/`le`/`gt`/`ge`（`{"<op>": {"field": "<name>", "value": <scalar>}}`）、`in`（值为数组，空数组不匹配任何行）、`contains`/`startsWith`/`endsWith`（Text 上大小写敏感的子串/前缀/后缀，服务端扫描）、`icontains`（大小写不敏感 contains，用户输入搜索词优先用）、`and`/`or`/`not` 布尔组合。
8. 确保 `<scalar>` 匹配字段的 `typeName`：`null`→null_，`true`/`false`→bool，`0`/`1`/`42`→nat（也可通过数值桥接匹配 Float），`-1`/`-42`→int（也可桥接 Float），`0.5`/`-3.14`/`1.0e2`→float，`"foo"`→text；字段为 `null_` 的行除 `ne` 外所有关系都失败；按关系过滤时 `field` 用边名、`value` 用目标实体的主键值。
9. 用聚合在 canister 端计算：`aggregate` 的 `fn` 为 `count`/`sum`/`avg`/`min`/`max`，除 `count` 外都需 `field`，`min`/`max` 也支持文本；`as` 重命名输出列（默认 `count`、`sum_<field>` 等）且不能含 `.`；点路径字段默认用 `_` 连接各段（`dept.budget` 的 sum → `sum_dept_budget`）；无 `groupBy` 的 `aggregate` 对整个过滤集输出一行（空匹配的 count 为 0）；无 `aggregate` 的 `groupBy` 是服务端 DISTINCT；输出行只含分组键和聚合列。
10. 用 `orderBy` 多键排序（第一子句为主，`dir` 默认 `"asc"`）、`offset` 丢弃前 N 个匹配、`limit` 最多保留 N 个、`select` 做子集投影（默认投影所有非隐藏字段，聚合时为分组键加聚合列）。
11. 前向（子→父）关系用点路径单查询：`"<edgeField>.<targetField>"` 可在 `where`、`groupBy`、`orderBy`、`aggregate.field`、`select` 中服务端读取；支持最多 4 跳的多跳链（如 `"manager.department.name"`）；可与聚合组合。
12. 点路径规则：头段必须是 schema 中 `role` 为 `{"edge": {"to": ...}}` 的字段，否则 trap（遍历由 schema 驱动，不靠名字猜测）；null 或悬空外键使整条点路径解析为 `null`（左连接），该行除 `ne` 外所有关系失败且投影为 `null`；跨实体聚合在 start 实体的行上运行（从 employee 对 `"department.budget"` 求 avg 是员工加权的），要按部门数字就从 department 开始，或按点路径分组并聚合 start 实体字段；选裸边字段（如 `"accountManager"`）仍返回外键标量，没有 `.*`，需逐个命名目标字段。
13. 反向（一父→多子）关系用两步查询：对单个父主键用 `eq`，对一批用 `in`，作用于边字段、值为目标实体主键值；当父条件只是普通谓词时无需批量，直接用前向边过滤（如 `{"eq":{"field":"accountManager.office","value":"Berlin"}}`）；当父集合需要自己的查询形状（top-N、排序、分页）时，先收集键再在边字段上用 `in` 批量，绝不要跑 N 个单独 `eq` 查询。
14. 两跳/自边连接（父键需先查找）用两个查询：第二个按第一个返回的键在自边上过滤（如先查 project 的 `lead`，再用该 email 查 employee 的 `manager`）。
15. 复合条件用 `and`/`or` 堆叠多个谓词。
16. 分页：显式设置 `limit`，用 `hasMore` 判断截断，用 `offset` 翻页（offset 从 0 开始，每页后 offset += limit，直到 hasMore 为 false）；OQL 本身无上限（省略 limit 返回所有匹配），canister 作者可能加上限，此时过量请求会被静默截断。
17. 出错时重试：没有结构化错误信封，任何失败都是 trap；重新读 schema、修正查询、重跑。
18. 常见陷阱排查：`unknown entity` 是 `start` 与 schema 的 `name` 不匹配（大小写敏感）；解析错误是 JSON 格式错（尾逗号、单引号）或未按 Candid text 字面量转义（先用 `python3 -m json.tool` 验证 JSON）；预期匹配却无行是字面量类型与 `typeName` 不符、字段名拼错（未知字段静默为 `null_`）或字段确实为 `null_`；跨类型 `gt`/`lt` 结果怪异是混合类型比较未定义，确保两操作数同 `typeName`；`contains` 漏行是大小写敏感，用户输入用 `icontains`；点路径 trap `'x' is not an edge of 'y'` 是头段非声明边，改用两步 `in` 模式；跨实体平均看起来不对是聚合在 start 实体行上运行；返回行缺字段是 `select` 了实体中不存在的字段，从 `select` 去掉或移除 `select` 用默认投影。
19. 需要读已部署 canister 而非草稿时加 `--branch live`（live 只读）；字符串值含单引号时用 `'\''` 为 shell 转义。

适用边界 · 注意事项

• canister 未暴露 OQL 接口（无 schema()/execute() 方法）时不适用。
• 需要写操作时不适用——OQL 的 schema() 和 execute() 都是只读 query 调用。
• 没有安装并配置好 `icp` CLI、或 canister 名 `backend` 无法解析到目标 canister 时不适用。