odata-execution

OData Execution

Build, test, and verify OData queries incrementally using dxs odata execute.

References

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

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)

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.

Step 1: Base entity with $select

Start with the root entity and only its scalar fields:

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

Step 2: Add one-to-one expands

Add navigation properties that return a single related entity:

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

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

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

Merge all verified layers into the final query. Only at this point should you remove $top=1 (if appropriate for the use case).

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.

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.

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

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

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
Rewriting the query after DXS-API-CONN / DXS-API-TLS / DXS-API-TIMEOUT / DXS-API-NET	Those are transport failures, not query errors — follow the payload's suggestions[]. See configuration-roundtrip.md → Exit 141 and transport errors