odata-execution

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OData Execution

OData 执行

Build, test, and verify OData queries incrementally using

dxs odata execute

使用

dxs odata execute

增量式构建、测试和验证OData查询。

References

参考资料

references/filter-patterns.md — Lambda operators, string functions, SQL-to-OData mappings

references/filter-patterns.md — Lambda运算符、字符串函数、SQL到OData的映射

Input/Output Contract

输入/输出约定

Input: Connection ID + entity knowledge (field names, navigation properties — from schema-explorer or conversation context)

Output: Verified OData query string (in conversation context, not a file)

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

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

Workflow — Incremental Query Building

工作流——增量式查询构建

Build queries one layer at a time. Large queries timeout, and adding one expand at a time isolates problems. A 400 on

$select

means the field name is wrong — check

schema properties

, don't drop

$select

逐层构建查询。大型查询会超时，每次只添加一个expand可以隔离问题。

$select

返回400错误意味着字段名错误——请检查

schema properties

，不要去掉

$select

。

Step 1: Base entity with

$select

步骤1：带有

$select

的基础实体

Start with the root entity and only its scalar fields:

bash

dxs odata execute -c <id> -q 'Entity?$top=1&$select=Id,Field1,Field2'

从根实体及其仅有的标量字段开始：

bash

dxs odata execute -c <id> -q 'Entity?$top=1&$select=Id,Field1,Field2'

Step 2: Add one-to-one expands

步骤2：添加一对一expand

Add navigation properties that return a single related entity:

bash

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

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

bash

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

Step 3: Add collection expands with nested expands

步骤3：添加带嵌套expand的集合expand

Add navigation properties that return collections, including any nested expansions:

bash

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)))'

添加返回集合的导航属性，包括所有嵌套展开：

bash

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)))'

Step 4: Combine everything into the full query

步骤4：合并所有内容生成完整查询

Merge all verified layers into the final query. Only at this point should you remove

$top=1

(if appropriate for the use case).

将所有已验证的层合并为最终查询。仅在此时才应移除

$top=1

（如果符合使用场景的话）。

Push Filtering Server-Side

服务器端过滤推送

Before accepting client-side filtering, verify whether the logic can be expressed in

$filter

. OData supports lambda operators for collection filtering, string functions, and nested

$filter

$expand

. See references/filter-patterns.md for the full pattern library.

在接受客户端过滤之前，请验证逻辑是否可以用

$filter

表达。OData支持用于集合过滤的Lambda运算符、字符串函数，以及

$expand

中的嵌套

$filter

。完整的模式库请参考references/filter-patterns.md。

Parameterized Queries (Key Segment)

参数化查询（键段）

For single-entity queries, use key segment syntax:

Entity(0)

. The

is a placeholder. Validate query structure with

Entity?$top=1

first, then switch to

Entity(0)

Entity(0)

returns 404 — this is expected (no entity with ID 0). Don't waste time re-testing.

bash

undefined

对于单实体查询，请使用键段语法：

Entity(0)

。其中

是占位符。先使用

Entity?$top=1

验证查询结构，再切换为

Entity(0)

。

Entity(0)

返回404是预期结果（不存在ID为0的实体），无需浪费时间重新测试。

bash

undefined

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)'

undefined

dxs odata execute -c <id> -q 'Entity(0)?$select=Id,Field1&$expand=Status($select=Id,Name)'

undefined

Critical Rules

重要规则

Rule	Detail
`$top=1` always	Use during testing to avoid timeouts
Single quotes	Always use `'...'` for `-q` (prevents `$` shell expansion)
`$select` in `$expand`	Required on every expand clause
Nested option separator	Semicolons ( `;` ) inside parentheses, not `&`
400 on `$select`	Field name is wrong — check `schema properties` , don't drop `$select`
Composite keys	Check `keys:` — some entities have no `Id` field

规则	详情
始终使用 `$top=1`	测试时使用以避免超时
单引号	`-q` 参数始终使用 `'...'` （防止 `$` 被Shell展开）
`$expand` 中包含 `$select`	每个expand子句都必须包含
嵌套选项分隔符	括号内使用分号( `;` )，而非 `&`
`$select` 返回400错误	字段名错误——请检查 `schema properties` ，不要去掉 `$select`
复合键	检查 `keys:` ——部分实体没有 `Id` 字段

Common Mistakes

常见错误

Mistake	Fix
`$expand` without `$select`	Always include `$select=Field1,Field2`
Double quotes for `$` values	Use single quotes — shell expands `$` in double quotes
Not using `$top=1` during query testing	Large queries timeout — always limit during development
Testing with `Entity(0)` and panicking at 404	404 is expected — validate structure via `$top=1` first

错误	修复方法
`$expand` 未包含 `$select`	始终加入 `$select=Field1,Field2`
使用双引号包裹含 `$` 的值	使用单引号——Shell会展开双引号中的 `$`
查询测试时未使用 `$top=1`	大型查询会超时——开发阶段始终限制返回数量
使用 `Entity(0)` 测试时因404错误惊慌	404是预期结果——先通过 `$top=1` 验证结构

odata-execution

Original

Translation

OData Execution

OData 执行

References

参考资料

Input/Output Contract

输入/输出约定

Workflow — Incremental Query Building

工作流——增量式查询构建

Step 1: Base entity with
`$select`

步骤1：带有
`$select`
的基础实体

Step 2: Add one-to-one expands

步骤2：添加一对一expand

Step 3: Add collection expands with nested expands

步骤3：添加带嵌套expand的集合expand

Step 4: Combine everything into the full query

步骤4：合并所有内容生成完整查询

Push Filtering Server-Side

服务器端过滤推送

Parameterized Queries (Key Segment)

参数化查询（键段）

First: validate structure

第一步：验证结构

Then: switch to key segment

第二步：切换为键段

Critical Rules

重要规则

Common Mistakes

常见错误

odata-execution

Original

Translation

OData Execution

OData 执行

References

参考资料

Input/Output Contract

输入/输出约定

Workflow — Incremental Query Building

工作流——增量式查询构建

Step 1: Base entity with $select

步骤1：带有$select的基础实体

Step 2: Add one-to-one expands

步骤2：添加一对一expand

Step 3: Add collection expands with nested expands

步骤3：添加带嵌套expand的集合expand

Step 4: Combine everything into the full query

步骤4：合并所有内容生成完整查询

Push Filtering Server-Side

服务器端过滤推送

Parameterized Queries (Key Segment)

参数化查询（键段）

First: validate structure

第一步：验证结构

Then: switch to key segment

第二步：切换为键段

Critical Rules

重要规则

Common Mistakes

常见错误

Step 1: Base entity with
`$select`

步骤1：带有
`$select`
的基础实体