@inf-monkeys-tech/monkeys-cli 0.12.11 → 0.12.13

package/skills/monkeys-data/references/ontology-feature-search.md

@@ -65,11 +65,57 @@ CLI 只校验 expression 公共结构和 JSON 标量形状。Feature 的真实
 - semantic/vector/description/fuzzy/full-text Feature search
 - JSON/object/relation/image/file Feature 类型
 - View/container scoped Feature
-- Feature sort、aggregation、facet、exists 或 null predicate
+- 任意关系遍历、多维 facet、exists 或 null predicate；标量 sort/select 与单维 aggregate 见下文，不能据此推断其他能力已经存在。
 - Feature 与 `current_and_shared` 跨 Team 查询
 
 不要把固定字段 `relation` expression 与 Relation 类型 Feature 混淆；后者当前不支持。
 
+## 最小字段投影与排序
+
+部署支持语义 `sort/select` 时，通过 `data asset search --filter-file <文件>` 指定 `viewId`、`sort` 和 `select`。普通 Studio 语义查询必须提供已确认的 Ontology 与可读 View；`--team` 只作为认证上下文，不在查询 JSON 中重复添加 `teamId`。自动视角携带的 `--resource-team` 不会注入 Studio advanced-search Body；Kernel 的显式资源定位规则不变。
+
+```json
+{
+  "viewId": "<view-id>",
+  "sort": { "field": { "kind": "feature", "fieldKey": "score" }, "order": "desc", "missing": "last" },
+  "select": [
+    { "field": { "kind": "builtin", "name": "name" }, "alias": "name" },
+    { "field": { "kind": "feature", "fieldKey": "score" }, "alias": "score" }
+  ]
+}
+```
+
+指定字段后，`items` 中每项为 `{ "assetRef": { "id": "...", "teamId": "...", "ontologyId": "..." }, "values": { "name": "...", "score": 0 } }`。身份与别名值分层保留，`null`、`0`、`false` 不代表字段丢失。不要套用普通 Asset 顶层 `id/name` 解析，也不要补拉完整 Asset。`select` 不与 `--compact` 同用；CLI 在请求前明确拒绝，防止丢失已选择的值。
+
+沿用统一 `--page-size/--page-token/--page-all/--page-limit`。变更 View、条件、select、排序、缺失值策略或 Context 后，必须从第一页开始。
+
+## 服务端通用聚合
+
+先查看 `monkeys schema data asset aggregate`。该命令只支持 `ontology-v1` 和 Studio，并要求 `--ontology`、`--view` 与 `--input-file` 或 `--input-json`。不要传 `--bucket`、`--resource-team`、输入 `teamId` 或 `timeoutMs`，也不要把 search 的 `filterConfigV2` 包装复制进聚合输入。
+
+```bash
+monkeys data asset aggregate --ontology <ontology-id> --view <view-id> --input-file aggregate.json --subscription <Subscription> --output json
+```
+
+`aggregate.json` 使用现有通用合同，例如：
+
+```json
+{
+  "expression": { "op": "feature", "fieldKey": "active", "cmp": "eq", "value": true },
+  "metrics": [
+    { "op": "count", "alias": "records" },
+    { "op": "value_count", "field": { "kind": "feature", "fieldKey": "score" }, "alias": "present" },
+    { "op": "sum", "field": { "kind": "feature", "fieldKey": "score" }, "alias": "scoreSum" }
+  ]
+}
+```
+
+- 可选一个 `groupBy`，字段使用 `builtin`、标量 `feature.fieldKey` 或 `tag_group.tagGroupId`；多个指标仍有上限。支持 `count/value_count/distinct_count/sum/avg/min/max`，实际字段类型和权限由服务端判定。`count` 不带字段，所有指标及分组 alias 必须唯一。
+- CLI 只调用已公开、稳定、只读且支持 Studio 的 `data.asset.aggregate`；不会猜地址、不以旧内置路由替代、不下载全量 Asset 后本地统计。找不到或不兼容时，停止并确认 Server 部署和 OpenAPI，不能靠刷新 CLI 把未部署的 Operation 变出来。
+- 结果仍为 `items/pageInfo`。`aggregatePages` 保留每一服务端页的 `scanned/exact/truncated/pageInfo` 及 `itemOffset`；多页不累加扫描量，也不把分页分组再算成一个虚假的总计。单次只返回一页时还提供顶层 `scanned/exact/truncated`。
+- `exact` 是服务端指标精确度声明，不等于已经读完全部组。必须同时检查 `pageInfo.hasMore` 与 `truncated`；任何缺页或截断都不能称为完整统计。近似 `distinct_count` 也不得说成精确去重数。`accuracy` 不是请求参数。
+- 默认单页；确有需要时才用有界 `--page-all --page-limit`。分页令牌绑定指标、分组、排序、筛选、Ontology/View 和 Context。服务端按指标排名不支持续页时，不得自行分页或改为本地全量排序。
+
 ## 错误处理
 
 - `DATA_SEARCH_EXPRESSION_INVALID`：请求未发送。修正节点路径、op、fieldKey、cmp、value 或表达式上限。