schema-explorer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Schema Explorer

Schema 探索器

OData schema discovery using

dxs schema

commands.

使用

dxs schema

命令进行OData Schema发现。

References

参考资料

references/batch-syntax.md — Batch command syntax, argument styles, describe-entity flags, anti-patterns
references/subagent-template.md — Subagent delegation prompt

references/batch-syntax.md — 批量命令语法、参数样式、describe-entity标志、反模式
references/subagent-template.md — 子代理委托提示

Resolving the Connection

解析连接

Schema commands require a connection ID (

-c <id>

). The user may or may not provide one explicitly.

If the user provides a connection ID or name — use it directly. Examples: "use connection 9", "use the Prod connection".

If the user says something like "in Prod" or "on the Demo environment" — find the matching FootprintApi connection:

```
dxs auth status
```
— get the authenticated organization ID

dxs organization connection list --org <org_id>

— list all connections

Filter to
```
apiConnectionTypeName: FootPrintApi
```
and match the name

If the user doesn't specify a connection at all — list the available FootprintApi connections and ask which one to use:

```
dxs auth status
```
— get the org ID

dxs organization connection list --org <org_id>

— list connections

Show the user just the FootprintApi connections (filter out MongoDB, AMQP, SFTP, etc.) and ask them to pick one

Schema命令需要连接ID（

-c <id>

）。用户可能会明确提供，也可能不会。

如果用户提供连接ID或名称 — 直接使用。示例："使用连接9"、"使用Prod连接"。

如果用户提到类似"在Prod环境"或"在Demo环境" — 查找匹配的FootprintApi连接：

```
dxs auth status
```
— 获取已认证的组织ID

dxs organization connection list --org <org_id>

— 列出所有连接

筛选
```
apiConnectionTypeName: FootPrintApi
```
并匹配名称

如果用户完全未指定连接 — 列出可用的FootprintApi连接并询问使用哪一个：

```
dxs auth status
```
— 获取组织ID

dxs organization connection list --org <org_id>

— 列出连接

仅向用户展示FootprintApi连接（过滤掉MongoDB、AMQP、SFTP等）并让其选择

Input/Output Contract

输入/输出约定

Input: Connection ID + search keywords

Output:

field-mapping.md

file with this structure:

markdown

undefined

输入： 连接ID + 搜索关键词

输出： 结构如下的

field-mapping.md

文件：

markdown

undefined

Schema: <EntityName>

Connection

连接

Connection ID: <id>
Namespace: <namespace>

连接ID: <id>
命名空间: <namespace>

Primary Entity

主实体

Entity Set: <name>
Entity Type: <namespace.type>
Keys: <key fields and types>

实体集合: <name>
实体类型: <namespace.type>
键: <键字段及类型>

Fields

字段

Root Fields

根字段

Field	Type	Notes

字段	类型	说明

Navigation Properties

导航属性

Nav Property	Target Type	Cardinality	Key Fields

导航属性	目标类型	基数	键字段

Expanded Fields (via $expand)

扩展字段（通过$expand）

Path	Type	Source Entity	Binding

Mark the Binding column:

```
flat
```
— field is reachable through single navigation properties; safe for flat DataSet fields
```
⚠ collection
```
— path crosses a collection navigation property (1:N cardinality); requires flow datasource flattening or child dataset with
```
CommandText
```
deep path. Will silently render blank if added as a flat DataSet field.

路径	类型	源实体	绑定类型

绑定类型列标记规则：

```
flat
```
— 字段可通过单一导航属性访问；适用于扁平DataSet字段
```
⚠ collection
```
— 路径跨越集合导航属性（1:N基数）；需要流数据源扁平化或使用
```
CommandText
```
深层路径的子数据集。如果作为扁平DataSet字段添加，会静默渲染为空。

Composite Keys / Special Notes

复合键 / 特殊说明

undefined

undefined

Command Selection Rule

命令选择规则

Single request → use the direct command. Multiple independent requests → combine into ONE batch.

If you only need one operation (e.g., one search, one describe), use the direct command — don't wrap it in
```
dxs schema batch
```
with a single
```
--request
```
.
If you need 2+ independent operations, combine ALL of them into a single
```
dxs schema batch
```
call. Don't split independent requests across multiple batch calls — each call is a separate HTTP roundtrip.
Only split into a second call when results from the first call determine what to query next.

单一请求 → 使用直接命令。多个独立请求 → 合并为一个批量命令。

如果仅需一个操作（如一次搜索、一次描述），使用直接命令 — 不要用单个
```
--request
```
将其包装在
```
dxs schema batch
```
中。
如果需要2个及以上独立操作，将所有操作合并到一个
```
dxs schema batch
```
调用中。不要将独立请求拆分到多个批量调用中 — 每个调用都是一次单独的HTTP往返。
仅当第一个请求的结果决定后续查询内容时，才拆分到第二个调用。

Workflow

工作流程

Search for entities — Combine ALL keyword searches into one batch:
bash
```
dxs schema batch -c <id> \
  --request 'search shipment' \
  --request 'search order' \
  --request 'search warehouse' \
  --request 'search carrier'
```
If you can guess entity set names, combine searches with describes in the same batch. Search results include the full qualified
```
entity_type
```
(e.g.,
```
Datex.FootPrint.Api.Warehouse
```
) — save these for
```
--entity-type
```
flags in later steps.
For a single keyword, use the direct command:
```
dxs schema search "keyword" -c <id>
```
.

Describe entities and relationships — Combine ALL entity descriptions and relationship exploration into one batch. Use

--compact --no-udf

on describe-entity and

--depth 2

on relationships:

bash

dxs schema batch -c <id> \
  --request 'describe-entity Shipments --compact --no-udf' \
  --request 'describe-relationships Shipments --depth 2' \
  --request 'describe-entity Orders --compact --no-udf' \
  --request 'describe-relationships Orders --depth 2' \
  --request 'describe-entity ShipmentLines --compact --no-udf' \
  --request 'describe-relationships ShipmentLines --depth 2'

Use

--compact

for initial exploration. If you need full details on specific fields later, use

--select Field1,Field2

to describe only those properties.

Scan related entity fields — Combine ALL related entity scans into one batch. For each navigation property target you plan to
```
$expand
```
, use
```
describe-entity --compact --no-udf
```
:
bash
```
dxs schema batch -c <id> \
  --request 'describe-entity Materials --compact --no-udf' \
  --request 'describe-entity Lots --compact --no-udf' \
  --request 'describe-entity Addresses --compact --no-udf' \
  --request 'describe-entity Contacts --compact --no-udf' \
  --request 'describe-entity Warehouses --compact --no-udf' \
  --request 'describe-relationships Warehouses --depth 2'
```
Skip entities already covered by
```
describe-relationships --depth 2
```
in step 2 — depth-2 output includes nested nav property names and target types. Only scan entities where you need the scalar field list for
```
$select
```
clauses.
When you only have the type ID (e.g.,
```
Datex.FootPrint.Api.Warehouse
```
from relationship output) and don't know the entity set name, use
```
properties --entity-type Namespace.Type
```
instead — it accepts the full qualified type directly. Use
```
navigation-properties --entity-type
```
alongside it if you also need
```
$expand
```
paths.
Note: If you need
```
$expand
```
paths for a related entity (what can be expanded from it), those are in its
```
navigation_properties
```
output —
```
describe-entity --compact
```
includes both scalar properties and nav properties.
Resolve enum values — When a property's type doesn't start with
```
Edm.
```
, it's an enum or complex type. Combine all enum lookups into one batch (or use a single direct command if only one):
bash
```
dxs schema batch -c <id> \
  --request 'describe-enum Datex.FootPrint.Api.Statuses' \
  --request 'describe-enum Datex.FootPrint.Api.OrderTypes'
```
This tells you what filter values mean (e.g.,
```
StatusId eq 1
```
→ "Active").
Verify expansion paths — Invoke the
```
odata-execution
```
skill to confirm nav properties return data (
```
$top=1
```
+
```
$expand
```
). Some entities have nav properties with NULL foreign keys resulting in empty expansions.
What to verify:
- Deep paths (depth >= 2, e.g.,
```
OrderLine.Material.Description
```
  ) — higher failure risk
- Paths through nullable foreign keys (e.g.,
```
ShipToContact
```
  when
```
ShipToContactId
```
  is nullable)
- Collection-through-collection expansions (e.g.,
```
ShipmentLines($expand=OrderLine(...))
```
  )
- Any path you are not confident about
Safe to skip: Single-level expansions to lookup entities (Status, Type, Category patterns) where the foreign key is non-nullable. These are structurally guaranteed by the schema.
Note gaps and suggest alternate query paths (e.g., querying the related entity directly with a filter). Also test lambda operators (
```
any()
```
/
```
all()
```
) if you need to filter within expanded collections.
Build field mapping table — Compile all discovered fields into the field mapping template, separating root fields from navigation properties and expanded fields.

Address gaps explicitly. If the user asked about a concept (e.g., "success/failure", "late orders", "priority") and the schema has no direct field for it, say so in the field mapping. Explaining what doesn't exist is as valuable as documenting what does — it saves the user from searching for something that isn't there, and lets them decide on a workaround (derived calculation, external lookup, etc.).

搜索实体 — 将所有关键词搜索合并为一个批量命令：
bash
```
dxs schema batch -c <id> \
  --request 'search shipment' \
  --request 'search order' \
  --request 'search warehouse' \
  --request 'search carrier'
```
如果能猜到实体集合名称，可在同一个批量命令中结合搜索与描述操作。搜索结果包含完整的限定
```
entity_type
```
（如
```
Datex.FootPrint.Api.Warehouse
```
） — 保存这些内容用于后续步骤中的
```
--entity-type
```
标志。
对于单个关键词，使用直接命令：
```
dxs schema search "keyword" -c <id>
```
。

描述实体与关系 — 将所有实体描述和关系探索合并为一个批量命令。在describe-entity上使用

--compact --no-udf

，在relationships上使用

--depth 2

：

bash

dxs schema batch -c <id> \
  --request 'describe-entity Shipments --compact --no-udf' \
  --request 'describe-relationships Shipments --depth 2' \
  --request 'describe-entity Orders --compact --no-udf' \
  --request 'describe-relationships Orders --depth 2' \
  --request 'describe-entity ShipmentLines --compact --no-udf' \
  --request 'describe-relationships ShipmentLines --depth 2'

初始探索使用

--compact

。如果之后需要特定字段的完整详情，使用

--select Field1,Field2

仅描述这些属性。

扫描关联实体字段 — 将所有关联实体扫描合并为一个批量命令。对于计划使用

$expand

的每个导航属性目标，使用

describe-entity --compact --no-udf

：

bash

dxs schema batch -c <id> \
  --request 'describe-entity Materials --compact --no-udf' \
  --request 'describe-entity Lots --compact --no-udf' \
  --request 'describe-entity Addresses --compact --no-udf' \
  --request 'describe-entity Contacts --compact --no-udf' \
  --request 'describe-entity Warehouses --compact --no-udf' \
  --request 'describe-relationships Warehouses --depth 2'

跳过步骤2中

describe-relationships --depth 2

已覆盖的实体 — 深度为2的输出包含嵌套导航属性名称和目标类型。仅扫描需要标量字段列表用于

$select

子句的实体。

当仅拥有类型ID（如关系输出中的

Datex.FootPrint.Api.Warehouse

）且不知道实体集合名称时，改用

properties --entity-type Namespace.Type

— 它直接接受完整的限定类型。如果还需要

$expand

路径，可同时使用

navigation-properties --entity-type

。

注意： 如果需要关联实体的

$expand

路径（从该实体可扩展的内容），这些信息在其

navigation_properties

输出中 —

describe-entity --compact

同时包含标量属性和导航属性。

解析枚举值 — 当属性类型不以
```
Edm.
```
开头时，它是枚举或复杂类型。将所有枚举查询合并为一个批量命令（如果仅需查询一个，使用单个直接命令）：
bash
```
dxs schema batch -c <id> \
  --request 'describe-enum Datex.FootPrint.Api.Statuses' \
  --request 'describe-enum Datex.FootPrint.Api.OrderTypes'
```
这会告知你筛选值的含义（如
```
StatusId eq 1
```
→ "Active"）。
验证扩展路径 — 调用
```
odata-execution
```
技能确认导航属性返回数据（
```
$top=1
```
+
```
$expand
```
）。部分实体的导航属性可能存在NULL外键，导致扩展结果为空。
需要验证的场景：
- 深层路径（深度≥2，如
```
OrderLine.Material.Description
```
  ） — 失败风险更高
- 可为空外键的路径（如
```
ShipToContactId
```
  为空时的
```
ShipToContact
```
  ）
- 集合到集合的扩展（如
```
ShipmentLines($expand=OrderLine(...))
```
  ）
- 任何你不确定的路径
可安全跳过的场景： 外键不可为空的单级扩展到查询实体（Status、Type、Category模式）。这些在结构上由Schema保证。
记录缺口并建议替代查询路径（如直接查询关联实体并添加筛选条件）。如果需要在扩展集合内筛选，也测试lambda运算符（
```
any()
```
/
```
all()
```
）。
构建字段映射表 — 将所有发现的字段整理到字段映射模板中，区分根字段、导航属性和扩展字段。

明确说明缺口。 如果用户询问某个概念（如"成功/失败"、"延迟订单"、"优先级"）但Schema中没有对应字段，需在字段映射中说明。解释不存在的内容与记录存在的内容同样重要 — 这能避免用户寻找不存在的内容，并让他们决定解决方案（派生计算、外部查询等）。

Subagent Usage

子代理使用

Schema exploration can generate significant output. Delegate to a subagent to keep the main context clean. See references/subagent-template.md for the prompt template.

Write output to the artifact directory:

```
01-schema-exploration.md
```
— raw schema discovery output
```
02-field-mapping.md
```
— completed field mapping table

Schema探索会生成大量输出。可委托给子代理以保持主上下文整洁。提示模板请参见references/subagent-template.md。

将输出写入工件目录：

```
01-schema-exploration.md
```
— 原始Schema发现输出
```
02-field-mapping.md
```
— 已完成的字段映射表

describe-entity Flags

describe-entity标志

describe-entity

does NOT support

--concise

. See references/batch-syntax.md for the full display flags table (

--compact

--no-udf

-P

-N

--prop-top

--select

). All flags work in batch:

--request 'describe-entity Orders --compact --no-udf'

describe-entity

不支持

--concise

。完整的显示标志表（

--compact

、

--no-udf

、

-P

、

-N

、

--prop-top

、

--select

）请参见references/batch-syntax.md。所有标志在批量命令中均有效：

--request 'describe-entity Orders --compact --no-udf'

Additional Rules

额外规则

Rules already embedded in the workflow steps above are not repeated here. See references/batch-syntax.md for the full anti-patterns table.

Always check the
```
keys:
```
section — some entities have composite keys (no
```
Id
```
field)
```
describe-properties
```
takes one property name at a time — not comma-separated; for bulk discovery use
```
describe-entity --compact --no-udf
```
or batch multiple calls
Batch eliminates the "run sequentially" constraint — unlike parallel tool calls (which abort siblings on failure), batch handles individual request failures gracefully

已嵌入工作流程步骤中的规则不再重复。完整的反模式表请参见references/batch-syntax.md。

始终检查
```
keys:
```
部分 — 部分实体拥有复合键（无
```
Id
```
字段）
```
describe-properties
```
一次仅接受一个属性名称 — 不支持逗号分隔；批量发现请使用
```
describe-entity --compact --no-udf
```
或批量调用多个命令
批量命令消除了"顺序执行"的限制 — 与并行工具调用（某个调用失败会终止其他调用）不同，批量命令能优雅处理单个请求失败的情况