Back to Details

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
in 
$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 
0
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)
。其中
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)'
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

重要规则

RuleDetail
$top=1
always		Use during testing to avoid timeouts
Single quotesAlways use 
'...'
for 
-q
(prevents 
$
shell expansion)
$select
in 
$expand
Required on every expand clause
Nested option separatorSemicolons (
;
) inside parentheses, not 
&
400 on 
$select
Field name is wrong — check 
schema properties
, don't drop 
$select
Composite keysCheck 
keys:
— some entities have no 
Id
field
规则详情
始终使用
$top=1
测试时使用以避免超时
单引号
-q
参数始终使用
'...'
（防止
$
被Shell展开）
$expand
中包含
$select
每个expand子句都必须包含
嵌套选项分隔符括号内使用分号(
;
)，而非
&
$select
返回400错误		字段名错误——请检查
schema properties
，不要去掉
$select
复合键检查
keys:
——部分实体没有
Id
字段

Common Mistakes

常见错误

MistakeFix
$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
验证结构