Query Builder 与 Tree Grid View

Query Builder（QB）负责定义数据结构与条件，Tree Grid View（TGV）负责把查询结果映射成树形表格。 两者是独立元数据：先证明 Query Definition 正确，再处理 TGV 的行、列和链接。

适用版本

本文以 R22 Query Builder 与 R27/R33 Tree Grid View 官方指南为基线。 目标 Release 的菜单、可映射数据类型和 OOTB Query Definition 可能不同，升级后必须重跑验证。

---

1. 两层职责

每个 TGV 关联一个 Query Definition；Query Definition 又基于一个 Context ItemType。

• QB 决定查哪些元素、如何关联、递归和过滤。
• TGV 决定哪些查询元素变成行、单元格显示什么、是否链接到 Item。
• Usage 把完成的 TGV 挂到具体使用位置。

---

2. 建立 Query Definition

2.1 选择根元素

根元素应对应业务上下文，例如 Part。先只选择少量稳定 Property：

id, item_number, name, state

保存后立即执行查询，确认根结果与普通搜索一致。

2.2 添加关系与关联 Item

逐层添加 Relationship 与 related Item，并明确 join 方向。 每增加一层就执行一次查询，避免最后才发现某个 join 为空。

2.3 条件

官方 Query Builder 支持比较、布尔逻辑和部分聚合表达式。 条件编辑器要求运算符两侧保留空格，例如：

[Name] like 'DOC%'

多词 Property 会使用方括号。不要直接粘贴 SQL WHERE 子句。

2.4 递归

BOM 等未知层级结构可使用 Query Definition 的递归配置。 递归前先准备：

• 小规模无环测试数据。
• 最大顶层结果数。
• 明确的关系方向。
• 对环路和超深结构的业务校验。

不要宣称所有循环都会固定表现为“堆栈溢出”；应在目标 Release 记录实际错误与限制。

---

3. 参数

Query Parameter 在 Query Definition 中定义，并可用于元素条件。 添加后，它会出现在 TGV 的 Map Parameters 对话框；映射完成后，用户可通过 Modify Parameters 设置运行值。

推荐为参数定义：

• 稳定内部名称。
• 用户可理解的 Label。
• 安全的 Default Value。
• 空值行为。
• 输入范围或允许值。

参数不会自动从主表单任意 Property 注入。若需要上下文传值，应使用 Usage 或目标版本支持的映射能力并实际验证。

---

4. Structure Resolution 不是通用枚举

OOTB Part BOM TGV 配置了特殊的 Structure Resolution Parameter，支持：

• Latest。
• Released。
• Released or Latest。

这套行为依赖特殊参数与版本化 Item 规则，并不是任意 AML get 都能加上 queryType 获得的通用能力。 自定义结构要按 Query Builder 指南完成专门配置。

---

5. 创建 Tree Grid View

1. 新建 Tree Grid View。
2. 选择经过验证的 Query Definition。
3. 建立所需列。
4. 把查询元素映射为 TGV 行。
5. 将查询 Property 映射到具体单元格。
6. 为需要跳转的单元格配置 Item 映射。
7. 保存并预览。

Item 类型单元格要提供正确的 ItemType Name 与 ID Template，才能生成有效链接。 Relationship 与 related Item 可以按展示需要分行，也可以在指南支持的场景中组合行。

先文本，后样式

先用 Text 映射证明值正确，再设置 Date、Decimal、Item、List 等类型。 某些 Property 类型在特定 Release 不能直接映射，必须查当期 TGV 指南。

---

6. 挂载为 Relationship Tab

官方 Set Tree Grid View Usage Action 可以创建 RelationshipType，并把 TGV 作为 Context ItemType 的自定义关系视图。

1. 选中 TGV。
2. 执行 Set Tree Grid View Usage。
3. 选择 Relationship Tab。
4. 选择 Relationship Name。
5. 为根节点定义 Starting Conditions，通常限制到当前 Item ID。
6. 点击 Generate。
7. 注销并重新登录后检查页签。

Action 只运行一次

官方指南明确说明，第二次运行会因 RelationshipType 已存在而报错。 后续应直接修改 TGV 和 Query Definition，而不是反复 Generate。

不要把“直接发布到 TOC”写成所有版本的 TGV 标准 Usage；如果项目需要独立入口，应按目标版本的 CUI/TOC 文档另行配置。

---

7. 权限表现

Query Builder 执行结果受用户标准 Get 权限约束。 官方指南说明：当一行同时包含 Relationship 与 related Item 信息，而用户无权读取 related Item 时， 相关单元格可能为空；若配置显示其 keyed_name，可能显示 Restricted。

因此不要笼统写成“无权节点和全部子节点必然被隐藏”。 权限回归应观察每个元素、单元格和链接的实际结果，并确认没有敏感值泄漏。

---

8. 可复现实验：两层结构

8.1 Query Definition

1. 准备一个根 Item、两个有权读取的 related Item 和一个无权读取的 related Item。
2. 建立根、Relationship、related Item 三个元素。
3. 只选择 ID、业务键、名称和关系数量。
4. 设置较小 Max Count 并执行。
5. 保存原始查询结果作为基线。

8.2 TGV

1. 创建三列：编号、名称、数量。
2. 映射根行与子行。
3. 把编号设为 Item 链接。
4. 预览并逐个点击链接。
5. 添加参数过滤名称，再验证 Modify Parameters。

8.3 权限

1. 用管理员记录完整结果。
2. 用受限账号执行同一 TGV。
3. 记录空单元格、Restricted 与链接行为。
4. 确认页面源数据和导出文件都没有泄漏受限属性。

8.4 Usage

1. 运行一次 Set Tree Grid View Usage。
2. 打开当前 Context Item，确认只返回与当前 ID 相关的根。
3. 再创建另一个 Context Item，确认数据不会串项。

---

9. 常见错误

QB 未验证就开始做 TGV 样式

先执行 Query Definition，确认结构、数量和权限，再映射表格。

把 SQL 写进 Query 条件

使用 Query Builder 支持的条件语法，不直接拼接 SQL。

把 Latest/Released 当任意查询参数

它是 OOTB BOM 的 Structure Resolution 配置，需要特殊参数与模型支持。

重复运行 Set Tree Grid View Usage

Usage 已生成后直接维护既有 RelationshipType、TGV 和 Query Definition。

断言无权限节点一定消失

官方行为可能是相关单元格为空或 keyed name 显示 Restricted；按实际映射验证。

---

10. 官方依据

• Creating Tree Grid Views — R33
• Mapping Data into the Table — R33
• Attaching the Tree Grid View — R27
• Adding/Editing Query Parameters — R22
• Executing Queries — R22

文档最后核验：2026-08-13。