Order API Usage Across Seven Languages
Use this page to choose an API and interpret its result. Work through the Java, Rust, TypeScript, Python, Go, C# / .NET or Swift tutorial for native code in context.
The authority is the retained application source and its dated execution receipt. These are model-derived API spellings, not instructions to translate arbitrary English method names between languages. For another model, request scoped Assist; keep generated domain-library source unchanged.
Choose a query result
| Need | Use | Interpret the result |
|---|---|---|
| One Order to edit | Full scalar Order plus complete bounded item selection; require exactly one match. | Typed entities with loaded-state and version information. A minimal projection is insufficient for a full edit. |
| List screen | Bounded projection, stable ordering and explicitly selected child preview. | Typed SmartList. A one-item preview does not describe the full Order. |
| Single nullable field | Minimal Order request with that field explicitly selected. | An E expression distinguishes selected value, selected SQL NULL and NotLoaded. |
| Filtered total count | Explicit count on the same filtered request. | Total is metadata of the matching set, not the returned page length. |
| Status/currency totals | Provider aggregate request carrying the same filters. | Analytic rows, not hydrated Order entities. |
| Status buckets with empty categories | Facets with the explicit include-all/matched-only choice. | Facet result carrier separate from the returned Order page. |
All executed requests require a non-empty comment and purpose. context supplies
the trusted execution environment. The v1.0 examples' buyer predicates do not
establish authentication or tenant authorization.
| Language | Typed list terminal | Selected Order total expression | Item relation carrier |
|---|---|---|---|
| Java | executeForList(context) | E.customerOrder(order).getTotalMinor().eval() | order.getOrderItemList() |
| Rust | execute_for_list(context).await? | E::customer_order(&order).get_total_minor().eval() | Keep let handle = order.order_item_list() alive, then inspect handle.value(). |
| TypeScript | await request.executeForList(context) | E.customerOrder(order).totalMinor().eval() | order.orderItemList() |
| Python | await request.execute_for_list(context) | E.customer_order(order).total_minor().eval() | order.order_item_list() |
| Go | ExecuteForList(context) plus returned error | customer_order.NewCustomerOrderExpression(order).TotalMinor().Eval() | order.OrderItemList().Items() |
| C# / .NET | await request.ExecuteForListAsync(context) | E.CustomerOrder(order).TotalMinor().Eval() | order.OrderItemList |
| Swift | try await request.executeForList(context) | try E.customerOrder(order).totalMinor().eval() | order.orderItemList |
The list is the runtime's typed SmartList, with language-specific iteration and
metadata access. Iteration syntax such as .map, .Data or .data does not make
it an untyped SQL-row result. The application helpers named required, load,
graph, edit, pageRows and report are defined in the examples; they are not
extra generated APIs.
Preserve loaded state
An empty item list means no matching children only when that relation was selected. An omitted relation does not become a loaded empty collection. Use full reloading before an edit and a minimal projection only for a read-only view.
| Order note state | eval | Null-only fallback |
|---|---|---|
Selected Leave at reception | That text | That text |
| Selected SQL NULL | Native null/None/nil representation | No note |
| Selected empty string | Empty string | Empty string |
| Not selected | Native NotLoaded diagnostic | The same missing-field failure |
| Language | Null-only operation on the selected note expression |
|---|---|
| Java | getOrderNote().orIfNull("No note") |
| Rust | get_order_note().or_if_null(Some("No note".to_owned())) |
| TypeScript | orderNote().orElse("No note") |
| Python | order_note().or_if_null("No note") |
| Go | OrderNote().OrElse(&fallback); ordinary Eval() returns value/presence. |
| C# / .NET | OrderNote().OrIfNull("No note") |
| Swift | try orderNote().orElse("No note") |
These are the exact example-specific accessor names. A NotLoaded error calls for
selecting the field; it is not a reason to catch the error and return the null
default. The retained note-value, note-null, note-empty and note-not-loaded
phases establish all four cases.
Save a complete business edit
Load one DRAFT Order and every item needed to compute its total. The tutorial supports at most 100 items, so it loads up to 101 and rejects overflow. Validate quantities and money before mutation: the KSML scalar type alone does not enforce integer USD cents, integral quantities, the application bounds or legal state transitions.
An audit reason describes the actual business write. It does not create an application transaction spanning unrelated calls.
| Language | Transaction boundary used by the core draft edit | Important ownership rule |
|---|---|---|
| Java | Audited Order graph save. | Keep the selected changed item in the saved Order graph. Explicit line removal and the separate lifecycle program use native explicit transactions. |
| Rust | Typed execute_in_transaction scope with save_audited for Order and item. | A detached child clone must be saved explicitly in the same transaction. |
| TypeScript | Awaited audited Order graph save. | Mutate the selected child belonging to that graph; validate safe integer arithmetic. |
| Python | Awaited audited Order graph save. | Reject booleans as quantities; preserve async failures and cancellation. |
| Go | Audited Order graph save with checked returned error. | Do not ignore either (value, present) or the mutation error. |
| C# / .NET | Awaited audited Order graph save inside the owned connection scope. | Use checked arithmetic and keep the connection alive through completion. |
| Swift | Awaited audited Order graph save. | Mutate the child inside the parent value that will be saved. |
Use the persisted typed value returned by save, or reload it explicitly. Catch a version conflict at the business boundary, reload authoritative state and decide whether the request is still appropriate. Busy/locked, timeout, checker rejection and provider failures need their own diagnosis; a blind retry policy can conceal a broken transaction or overwrite the intended decision.
For line deletion, explicitly mark the intended child for deletion and recompute the complete total within one transaction. Omitting a child from a selected preview is not a delete command. For state changes, validate the current/target pair in application code before setting the generated status field; a generated setter is not the transition policy.
Advanced mutation recipes
Read the operation in your language with its complete example open:
| Language | Explicit deletion | Allowed state changes | Stale-version recovery |
|---|---|---|---|
| Java | Remove a line | Apply policy | Preserve the winner |
| Rust | Remove a line | Apply policy | Preserve the winner |
| TypeScript | Remove a line | Apply policy | Preserve the winner |
| Python | Remove a line | Apply policy | Preserve the winner |
| Go | Remove a line | Apply policy | Preserve the winner |
| C# / .NET | Remove a line | Apply policy | Preserve the winner |
| Swift | Remove a line | Apply policy | Preserve the winner |
For explicit deletion, Java and Rust save the recomputed Order and marked child through one explicit transaction, Order first. The other five use one audited save of the complete loaded graph. This differs from Java's core quantity-edit recipe; a graph can schedule deletes first. The recipes explain the exact native boundary instead of assuming identical write scheduling across runtimes.
A status setter is not the state-transition policy. The application allows only
DRAFT → CONFIRMED, DRAFT → CANCELLED and CONFIRMED → CANCELLED; repeated states,
reversals and unknown targets reject before save. A transition result's
observedVersion describes the loaded revision; read committed state again for
the new version. Cancelling an Order in this v1.0 example neither deletes its
items nor releases inventory.
Keep policy rejection, optimistic-version rejection and provider failure distinct. The controlled stale race retains two version-1 copies, commits B first, and then requires A to fail while every field of B's committed version-2 result stays unchanged. Several test-worker adapters collect broad errors under a report label; that label alone is not a production conflict classifier. Preserve the native error and inspect authoritative state before choosing a new business attempt.
These recipes use a fresh seed per branch. After a successful removal the target Order is total 2500/version 2 with a Pen tombstone at -2. In the stale-removal control the independently committed Pen stays live at version 2 while the attempted Order-total write rolls back to total 3850/version 1. Those are different outcomes; “rollback” does not erase a competing transaction's commit.
Choose a paging strategy
| Reader action | Existing API path | What to keep stable |
|---|---|---|
| Open a small search page | Offset/limit with stable total/ID order and exact count. | Filters, ordering, validated bounds and relation-preview limits. |
| Export consecutive pages | Continuous-page optimization on an ID-ordered request. | Reuse the trusted context and sequence key for the sequence. Inspect the actual cursor/fallback plan. |
| Jump between distant pages | Retained-ID pagination with explicit TTL and capacity. | Matching-set scope, ordering, buyer/tenant isolation, expiry and invalidation. |
| Calculate totals for a list screen | Provider aggregates and Facets with the same filters. | Do not sum a truncated page to obtain the total of the complete matching set. |
| Language | Bounded-page call in the retained example | Exact total carrier |
|---|---|---|
| Java | offset(offset, limit).count() | page.getTotalCount() |
| Rust | offset(offset as u64, limit as u64).count() | page.total_count |
| TypeScript | offset(offset).limit(limit).count() | page.totalCount |
| Python | offset(offset).limit(limit).count() | page.total_count |
| Go | Offset(uint64(offset)).Limit(uint64(limit)).Count() | page.TotalCount; check the pointer before dereferencing. |
| C# / .NET | Offset(offset).Limit(limit).Count() | page.TotalCount |
| Swift | offset(offset).limit(limit).count() | page.totalCount |
Validate signed offset/limit before unsigned casts. In this example the accepted
range is offset at least zero and limit 1–3. A selected child limit(1) is a
per-parent preview limit; it does not change the exact parent count.
The original fixture teaches the three-order edit.
The pagination fixture has nine Orders,
eight matching BUYER-EXPORT. The summary/retained-ID fixture
has ten Orders and adds currency/status conditions. They share model v1.0 but
must use separate databases. Do not expect the three-order edit database to
produce the export fixture's counts.
Use the native bounded-page excerpt in your language tutorial. Then read the
continuous export,
retained-ID and
summary explanations
with the corresponding full application function open. Java aggregates use
aggregation(context).toList(); the other six use the recorded analytic-row
terminal (execute_for_rows, executeForRows, ExecuteRecords or
ExecuteForRowsAsync). Analytic records have language-specific Value/alias
carriers; use the language troubleshooting page before adding casts.
Export, retained-ID and summary recipes
Choose the walkthrough for your runtime before copying an optimizer call:
| Language | Consecutive export | Random page jumps | Full-set summaries |
|---|---|---|---|
| Java | Export | Retained IDs | Summaries |
| Rust | Export | Retained IDs | Summaries |
| TypeScript | Export | Retained IDs | Summaries |
| Python | Export | Retained IDs | Summaries |
| Go | Export | Retained IDs | Summaries |
| C# / .NET | Export | Retained IDs | Summaries |
| Swift | Export | Retained IDs | Summaries |
Native optimizer spellings
These are request-builder methods from the retained v1.0 examples. Namespace, TTL and maximum IDs are explicit inputs; 300 seconds and capacity 20 are example values, not universal runtime defaults. Execute the completed bounded request with its comment, purpose and trusted context.
| Language | Continuous-page configuration | Retained-ID configuration |
|---|---|---|
| Java | optimizeForContinuousPageFetch(namespace, ttl) | optimizePaginationWithIdSet(namespace, ttl, maxIds) |
| Rust | optimize_for_continuous_page_fetch_with(namespace, ttl) | optimize_pagination_with_id_set_config(namespace, ttl, max_ids) |
| TypeScript | optimizeForContinuousPageFetchWith(namespace, ttl) | optimizePaginationWithIdSetConfig(namespace, ttl, maxIds) |
| Python | optimize_for_continuous_page_fetch_with(namespace, ttl) | optimize_pagination_with_id_set_config(namespace, ttl, max_ids) |
| Go | OptimizeForContinuousPageFetchWith(namespace, ttl) | OptimizePaginationWithIDSetConfig(namespace, ttl, maxIDs) |
| C# / .NET | OptimizeForContinuousPageFetchWith(namespace, ttl) | OptimizePaginationWithIdSet(namespace, ttl, maxIds) |
| Swift | optimizeForContinuousPageFetch(namespace: namespace, ttlSeconds: ttl) | optimizePaginationWithIdSet(namespace: namespace, ttlSeconds: ttl, maxIds: maxIds) |
Keep the context alive through one sequence. Calling the console again creates another process/context; an identical namespace does not restore an in-memory cursor or retained store. The export uses ID ordering and the nine-order fixture. Retained IDs use total/ID ordering and buyer plus USD predicates on the ten-order fixture. Selecting the wrong fixture changes the meaning of the expected count before any optimizer is involved.
Observe the actual plan and count
| Language | Continuous observation | Retained observation |
|---|---|---|
| Java | context.getAttribute(PortableSQLRepository.CONTINUOUS_PAGE_PLAN) | Attributes PortableSQLRepository.ID_SET_PLAN and PortableSQLRepository.ID_SET_COUNT. |
| Rust | context.continuous_page_plan() | context.id_set_plan() and context.id_set_count(). |
| TypeScript | context.continuousPagePlan | context.idSetPaginationPlan and context.idSetPaginationCount. |
| Python | context.continuous_page_plan() | context.id_set_plan() and context.id_set_count(); returns (count, accuracy); the report uses index 0. |
| Go | context.ContinuousPagePlan() | context.IDSetPlan() and context.IDSetCount(); returns (count, accuracy), not a presence flag. |
| C# / .NET | context.ContinuousPagePlan | context.IdSetPlan and context.IdSetCount. |
| Swift | await context.continuousPageObservation() | await context.idSetPaginationObservation() with plan and count. |
The Java constant owner is io.teaql.core.sql.portable.PortableSQLRepository.
Read observations immediately after their request. Keep the native value when
recording the operation; a previous request's observation or a hand-written plan
label is not evidence for the current query.
| Observation | Correct meaning in these examples |
|---|---|
CURSOR_SEEK | The runtime chose a seek plan; the retained SQL contains an ID boundary. |
OFFSET_FALLBACK:FIRST_PAGE / CACHE_MISS | Expected first/missing-cursor fallback. The empty export tail still has exact total 8. |
| Unsupported composite-sort fallback | Expected for total/ID sorting in this continuous ID-seek path; reason names vary by language. |
ID_SET_BUILD / ID_SET_HIT | Retained set construction/reuse, corroborated by actual store events and keys. |
ID_SET_FALLBACK_LIMIT_EXCEEDED | No partial ID set is retained. With capacity 4, observed count 5 is a lower bound; exact total 8 comes from provider COUNT. |
For retained IDs, Java/Rust/Python/Go/.NET wrap their native in-memory store for
observation. TypeScript's example implements the public store protocol itself.
Swift's public protocol exposes obtain, while its application actor adapter
implements invalidation by removing the delegate for the observed key. Do not
translate those adapters into nonexistent universal context invalidation methods.
Keep analytic carriers and native keys distinct
| Language | Provider-row terminal / carrier | Native status group key | Numeric/null handling in the example |
|---|---|---|---|
| Java | aggregation(context).toList() | Explicit alias statusId. | Analytic rows are passed into the report; Facets instead use typed status entities plus getDynamicProperty("count"). |
| Rust | execute_for_rows(context).await?, CompactRow | Explicit alias statusId. | get(key) and try_f64(); preserve optional overall sum. |
| TypeScript | executeForRows(context), analytic rows | orderStatus | Normalize key/count in the report, preserve overall totalMinor null. |
| Python | execute_for_rows(context), dictionaries | order_status | Convert known counts and preserve overall sum None. |
| Go | ExecuteRecords(context), Value records | order_status | TryU64()/TryF64(); nullable conversion for the empty overall sum. |
| C# / .NET | ExecuteForRowsAsync(context), .Rows of Value records | order_status | TryF64()/TryText() paths; non-null group helper and nullable overall-sum path are separate. |
| Swift | executeForRows(context), TeaQLRecord | orderStatus | .decimalValue conversion for reporting; optional overall sum maps to JSON null. |
The shared JSON field statusId is an application normalization for several
languages, not a promise that every unaliased native row contains statusId.
Analytic rows are not typed Order entities; E expressions and null-only entity
defaults do not replace their native record/value accessors.
Repeat buyer, currency and minimum amount on grouped aggregates, the overall aggregate, parent rows and both Facet variants. With all export-buyer USD orders, three visible rows do not change exact count 8 or sum 35350. With no matching buyer, grouped rows are empty but the overall aggregate is one row with count 0 and sum null. All-status Facets retain zero buckets; matched-only Facets omit them.
The query troubleshooting tables link native recovery guidance. These are fixed-data SQLite recipes: retained membership does not certify a transactionally frozen row snapshot, and query optimization does not implement file serialization, distributed retention or an unlimited-memory export loop.
Buyer/tenant authorization recipes
Use the v1.1 isolation model and its qualified application, rather than adding a client-supplied tenant field to the v1.0 query recipe. Choose the native walkthrough: Java, Rust, TypeScript, Python, Go, C# / .NET or Swift.
Ownership, context and request responsibilities
| Layer | Responsibility in the retained application | Boundary |
|---|---|---|
| Model v1.1 | Adds commerce_platform.tenant_key; Order → tenant root and item → Order use existing relations. | The sample key is not membership or authorization. Fresh bootstrap does not implement a live data migration. |
| Server session resolver | Selects an application-owned actor/tenant/buyer tuple. | Fixture keys a–d/readonly are synthetic, not credentials or public impersonation inputs. Real authentication is separate integration work. |
Native UserContext | Holds generated runtime/provider and retained-store execution state. | The facade receives a server-owned context; the examples do not rebind a native tenant/actor for each session. Swift explicitly keeps fixed server values and an identity RequestPolicy. |
| Application facade | Validates allowed fields, resolves exactly one tenant root, scopes all Order operations by root + buyer and permits only two narrow writes. | Enforced through these entry points. Arbitrary raw Q/database access is not automatically protected by this facade or SQL row-level security. |
| Transport adapter | Must parse/limit incoming data, authenticate, map responses and manage request/principal lifetime. | Console JSON probes do not certify a complete HTTP/TFP integration or exhaustive hostile-input handling. |
The allowed business fields are op, orderId, orderNumber, itemId, limit
and patch. Declared identity/policy fields are rejected before the first facade
SELECT. Limits default to 2 and require integer 1–2 when supplied. edit-note
accepts only orderNote; edit-item accepts only productName. Other patch keys
are rejected together, including identity, scope, amount, status and version.
Read-only sessions fail a valid write request before provider access. Keep native
validation semantics and preserve non-authorization provider exceptions.
Native scope, page and aggregate calls
Each handler first uses its native withTenantKeyIs/with_tenant_key_is equivalent
with bound 2 and requires exactly one root. These are the subsequent Order predicates:
| Language | Tenant-root + buyer on the Order request | Exact page / analytic result |
|---|---|---|
| Java | filterByCommercePlatform(root).withBuyerReferenceIs(s.buyer()) | .count().executeForList(context), getTotalCount(); summary aggregation(context).toList(). |
| Rust | with_commerce_platform_matching(Q::commerce_platforms().with_id_is(root)).with_buyer_reference_is(buyer) | execute_for_page(context, 0, limit).await?, .data/.total_count; summary analytic get + try_f64. |
| TypeScript | filterByCommercePlatform(root).withBuyerReferenceIs(buyer) | executeForPage(context, 0, limit), .data SmartList/page.totalCount; summary rows via executeForRows. |
| Python | filter_by_commerce_platform(root_id).with_buyer_reference_is(buyer) | execute_for_page(context, 0, limit), .data/.total_count; summary dictionaries via execute_for_rows. |
| Go | WithCommercePlatformIs(root).WithBuyerReferenceIs(buyer) | ExecuteForPage(context, 0, uint64(limit)), .Data/*TotalCount; summary ExecuteRecords + checked Value conversions. |
| C# / .NET | FilterByCommercePlatform(root).WithBuyerReferenceIs(buyer) | ExecuteForPageAsync(context, 0, limit), .Rows/.TotalCount; summary ExecuteForRowsAsync Value rows. |
| Swift | filterByCommercePlatform(root).withBuyerReferenceIs(buyer) | executeForPage(context, offset: 0, limit: limit), .items SmartList/.totalCount; summary TeaQLRecord .decimalValue. |
Keep the native request's comment, purpose and trusted execution context. A direct ID or repeated business-key condition narrows the already authorized request; it does not replace root/buyer scope. Resolve an item through its authorized parent, never through an unscoped item-ID read. Detail/edit paths load up to three children to detect the supported two-item maximum, then reject overflow; list previews remain bounded and retained pages omit children.
Every fixture scope has two Orders totaling 7700 USD cents. The summary's provider
COUNT/SUM repeats the same root + buyer predicates. The cache phase switches
a,b,c,a on one context and fixed order-isolation-shared namespace: expected
plans are BUILD, BUILD, BUILD, HIT with distinct authorized identities and total 2.
Typed predicate identity separates sets; a trusted namespace alone does not authorize
rows. Retain the .NET condition-key repair and TypeScript application-owned store.
Audited mutations and denial results
Note edits use complete authorized Order scalar state; Python/TypeScript/Go/.NET explicitly reload scalars without loaded children before the audited save. The other three keep their recorded parent-save semantics. Item edits save only the selected owned item. Audit reasons explain the change; they do not by themselves bind the native audit principal to the session actor shown in JSON.
| Facade code | Interpretation / caller action |
|---|---|
UNAUTHENTICATED | Resolve a valid server-side session before invoking the operation. |
FORGED_SCOPE, INVALID_REQUEST, INVALID_BOUNDS | Correct the business payload; do not accept/coerce client identity or broaden bounds silently. |
INVALID_TRUSTED_SCOPE | Repair missing/duplicate tenant provisioning; fail closed instead of taking the first root. |
NOT_FOUND | Same response for missing and foreign Order/item identities. No public unscoped diagnostic lookup. |
ITEM_LIMIT | Complete child-edit contract cannot be satisfied; reject the edit. |
FORBIDDEN_OPERATION, FORBIDDEN_FIELD | Session cannot write or patch is not the exact allowed shape; no partial write. |
OK, changed: true | One authorized note/label save completed; use fresh reads to inspect committed state. |
The exact-one and overflow guards are visible in source; the retained request catalog does not add a duplicate-root migration or oversized-item campaign. The dated isolation receipt combines named JSON responses, provider SQL and independent full SQLite snapshots. Read it with the coverage boundary and native troubleshooting tables. It does not establish timing non-enumeration, concurrent membership/revocation semantics, production migration or automatic RLS.
Scope versions and release status
| Scope | Local authority | Qualification |
|---|---|---|
| Core Order v1.0: edit, paging and summaries | 17-case receipt | Java and Swift published; Go, TypeScript, Rust, Python and .NET WORKSPACE PASS — RELEASE PENDING. |
| Buyer/tenant isolation v1.1 | Isolation receipt | Explicit trusted-session/root/actor extension; not inferred from a buyer filter. |
| Stock v1.2 | Stock receipt | Order, inventory and request receipt participate in the reservation transaction. |
| Request/COMMIT cleanup | Lifecycle receipt | Adds the Java JDBC workspace COMMIT-cleanup repair; earlier Java published scopes remain retained. |
| Finite concurrent load and cleanup | Soak receipt | Same lifecycle runtime identities; Swift published 0.3.1, six workspace runtimes pending release. |
Existing nullable generation, console guide, append and pagination Assist repairs remain pending generator deployment. Keep the generated workspace's recorded dependency manifest and source identity; do not upgrade or downgrade based on a version mentioned in an example's historical result. A workspace PASS is not a published-consumer PASS. The School baseline and every historical receipt remain separate authorities.
Diagnose a failed operation
First match the symptom against the native troubleshooting tables: Java, Rust, TypeScript, Python, Go, C# / .NET and Swift.
Match the operation's runtime, model revision and fixture before comparing its result with the recorded behavior. If a command, return shape or native error still differs, isolate that one operation on a disposable database and preserve the original error and dependency identity. The coverage matrix identifies available guidance and remaining recipe, packaging and integration work.