mcpField
O
odata-execution

odata-execution

github.com/datex数据与数据库115 次安装
代码仓库

关于 odata-execution

odata-execution 是一款使用 `dxs odata execute` 分步构建和验证 OData 查询的技能。它面向需要依据实体架构测试查询结构，并减少超时、定位错误的用户。

主要功能

  1. 01分阶段构建并验证查询
  2. 02选择实体字段
  3. 03添加嵌套展开
  4. 04将筛选下推到服务端
  5. 05检查键段查询

适用场景

  1. 01依据实体架构验证字段
  2. 02逐步测试嵌套展开
  3. 03区分传输故障与查询错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/datex/skills --skill odata-execution

安装后在 Claude Code 中输入/odata-execution确认已加载。

附带文件references/filter-patterns.md

详细介绍

OData 执行

使用 dxs odata execute 逐步构建、测试和验证 OData 查询。

参考资料

输入/输出约定

输入： 连接 ID + 实体知识（字段名称、导航属性——来自 schema-explorer 或对话上下文）

输出： 已验证的 OData 查询字符串（位于对话上下文中，而非文件）

工作流 — 逐步构建查询

每次构建查询的一层。大型查询会超时，每次添加一个 expand 有助于定位问题。$select 返回 400 表示字段名称错误——检查 schema properties，不要删除 $select。

步骤 1：使用 $select 查询基础实体

从根实体开始，仅选择其标量字段：

dxs odata execute -c <id> -q 'Entity?$top=1&$select=Id,Field1,Field2'
步骤 2：添加一对一 expand

添加返回单个关联实体的导航属性：

dxs odata execute -c <id> -q 'Entity?$top=1&$select=Id,Field1&$expand=Account($select=Id,Name),Status($select=Id,Name)'
步骤 3：添加带嵌套 expand 的集合 expand

添加返回集合的导航属性，包括任何嵌套扩展：

dxs odata execute -c <id> -q 'Entity?$top=1&$select=Id,Field1&$expand=Lines($select=Id,LineNumber;$expand=OrderLine($select=OrderId;$expand=Material($select=Id,Name)))'
步骤 4：合并所有内容，形成完整查询

将所有已验证的层合并到最终查询中。只有到这一步，才应移除 $top=1（如果符合使用场景）。

在服务器端进行筛选

接受客户端筛选之前，请先确认能否使用 $filter 表达相应逻辑。OData 支持用于集合筛选的 Lambda 运算符、字符串函数，以及 $expand 中的嵌套 $filter。完整模式库请参阅 references/filter-patterns.md。

参数化查询（键段）

查询单个实体时，请使用键段语法：Entity(0)。其中的 0 是占位符。先使用 Entity?$top=1 验证查询结构，然后再切换为 Entity(0)。

Entity(0) 返回 404 是预期行为（不存在 ID 为 0 的实体）。不要浪费时间重复测试。

# First: validate structure
dxs odata execute -c <id> -q 'Entity?$top=1&$select=Id,Field1&$expand=Status($select=Id,Name)'

# Then: switch to key segment
dxs odata execute -c <id> -q 'Entity(0)?$select=Id,Field1&$expand=Status($select=Id,Name)'

关键规则

规则详情
始终使用 $top=1测试时使用，以避免超时
使用单引号对 -q 始终使用 '...'（可避免 shell 展开 $）
在 $expand 中使用 $select每个 expand 子句都必须包含
嵌套选项分隔符括号内使用分号（;），而不是 &
$select 返回 400字段名称错误——检查 schema properties，不要删除 $select
复合键检查 keys:——某些实体没有 Id 字段

常见错误

错误修正方法
$expand 未包含 $select始终包含 $select=Field1,Field2
对 $ 值使用双引号使用单引号——shell 会展开双引号中的 $
测试查询时未使用 $top=1大型查询会超时——开发过程中始终限制结果数量
使用 Entity(0) 测试并因 404 而慌张404 是预期行为——先通过 $top=1 验证结构
在出现 DXS-API-CONN / DXS-API-TLS / DXS-API-TIMEOUT / DXS-API-NET 后重写查询这些是传输故障，而非查询错误——遵循载荷中的 suggestions[]。参阅 configuration-roundtrip.md → Exit 141 and transport errors

评论

支持 Markdown