aster.Web Data / Docs Aster UI ↗

Aster Web Data / Reference

OData support

What Aster Web Data supports of OData 4.01, area by area.

Supported by area

Aster Web Data implements OData 4.01 for the entity sets its DataSources define. The table lists what it serves, area by area; Not supported lists what answers an error instead.

Area Supported
Protocol OData 4.01. Requests with OData-Version 4.0 or 4.01 are accepted. OData-MaxVersion 4.0 gets 4.0 responses. Any other OData-Version, or a OData-MaxVersion below 4.0, is 400.
Service document GET <root>, listing the entity sets.
Metadata $metadata in CSDL XML (default) or JSON, chosen by Accept or $format. Messages are in the Accept-Language language. Vary names Accept-Language.
OpenAPI GET <root>/openapi.json, OpenAPI 3.1 from the same model as $metadata. Also exported with the command line.
Vocabulary /vocabularies/Aster.Data.V1.json and .xml, the vocabulary $metadata refers to. See AsterData vocabulary.
Resource paths An entity set. An entity by key: Set(1), a composite key Set(A=1,B='x'), or key segments Set/1/2. Set/$count. Navigation from an entity, chained, with a key after a collection-valued step, and /$count at the end. A property /Set(k)/Prop, and its raw value /Prop/$value. References /$ref. /$entity?$id= for the entity an ID names. /$all for the entities of every set, with $top, $skip and $count. POST <resource>/$query for query options in a body.
$filter Comparison operators eq, ne, gt, ge, lt, le, in, has, and logical operators and, or, not. Arithmetic add, sub, mul, div, divby, mod. Type tests isof and cast. Null handling per OData 4.01.
$filter functions String: tolower, toupper, trim, substring, length, indexof, contains, startswith, endswith. Date and time: year, month, day, hour, minute, second, fractionalseconds, date, time, totaloffsetminutes, totalseconds, now, maxdatetime, mindatetime. Math: round, floor, ceiling. Also concat, matchesPattern, case, hassubset and hassubsequence. Collation and pattern, in the AsterData namespace: AsterData.icontains, AsterData.istartswith, AsterData.iendswith, AsterData.like, AsterData.ilike, AsterData.regexp. See AsterData vocabulary.
Collections in $filter Nav/any(...) and Nav/all(...) over collection-valued navigations. Nav/$count in a filter. A lambda body may use the target's own navigations.
$orderby Primitive properties, asc and desc. Null ordering per OData 4.01. Key properties are added as tie-breakers, so paging is stable.
$top, $skip Evaluated in the order OData 4.01 gives. An over-large $top is clamped.
$count @odata.count with $count=true. It is the filtered total. See Counts.
$select Properties and *. The key is added unless the service sets select_without_keys.
$expand To-one and to-many navigations. Nested $select, $filter, $orderby, $top, $skip, $count and $expand. Nav/$count. $expand=* expands every navigation the item list does not name, and takes $levels only. $levels=n or $levels=max repeats a recursive navigation (one whose target is its own set). Nesting depth is limited by max_expand_depth.
$apply The Data Aggregation subset: filter(...), groupby((p,...)), groupby((p,...),aggregate(...)) with rollup(...) among the grouping properties, and aggregate(x with sum, min, max, average or countdistinct as a, $count as n), joined with /. The AsterData methods first, concat, concatDistinct and count also follow with. A grouping property may be a path through single-valued navigations that ends in a property. $filter, $orderby, $select, $top, $skip and $count apply to the result. Rows carry "@odata.id": null.
Hierarchies ancestors(...) and descendants(...) keep the set's entities that a walk reaches from start nodes. traverse(...) returns entities in tree order, with $distance and $rank. The walk is limited by max_traverse_depth.
$format, $skiptoken $format overrides Accept. $skiptoken is the opaque token of a server-driven page.
Server-driven paging A read larger than max_page_size (1,000 by default), or than Prefer: odata.maxpagesize, returns @odata.nextLink.
Writes POST (create, with the representation or return=minimal), PATCH and PUT (update), DELETE. Each write reads the row, decides from the stored row and the body, and runs as one transaction. Deep insert and deep update for owned navigations. Reference writes: PUT or DELETE on Set(k)/ToOne/$ref, and POST or DELETE on Set(k)/ToMany/$ref, or <nav>@odata.bind. Property writes on /Set(k)/Prop.
ETags Each entity carries @odata.etag and an ETag header. Updates and deletes use If-Match. The tag carries the values of the set's concurrency token (etag), which the database compares in the write. A set with an ETag requires If-Match (428 without it), and a stale or undecodable tag is 412. A set with etag: none or in etag_opt_out is last write wins; a set that declares no token has native on PostgreSQL and no ETag elsewhere.
Conditional reads If-None-Match matching a read's ETag (or *) answers 304.
$batch JSON batch. Members run in request order. An atomicityGroup runs as one transaction. $<id> refers to an earlier member's entity. If-Match: $<id> is supported. continue-on-error is set with Prefer: odata.continue-on-error. Without it, the first failure stops the batch, and each later request answers 424.
Operations Declared bound actions and functions, including Validate, changeKey, DeletePreview and the file operations of a FileSource set. Operations that run code are written in scripts or Rust handlers.
Set-based writes PATCH or DELETE on $each answers @AsterData.AffectedRows.
Response format JSON. odata.metadata set to minimal, full or none. IEEE754Compatible=true writes Int64 and Decimal values as strings. odata.include-annotations selects annotations. A body in another media type is 415.
Streaming Reads stream the body as rows arrive. A failure after the first byte ends the connection without completing the body.
Security Roles, owners and row restrictions per set, for read, insert, update and delete (security). A set the caller may not read is 403 wherever it is read. A property the caller may not read is null and listed in @AsterData.Hidden. Request context (Aster-Context) carries declared values. See Authentication and access.
Collation The column's own collation for text, published as AsterData.Collation on every text field.

Counts

$count=true returns an exact @odata.count after value. /$count and the counts of expanded navigations are exact too.

Preferences

Preference Effect
return=representation or return=minimal A write returns the entity, or no body.
odata.maxpagesize=N The page size the client wants. The smaller of this and max_page_size applies.
odata.continue-on-error A $batch keeps running after a failed member.
odata.include-annotations Which annotations the response carries.
aster.max-affected=N A cascading delete proceeds only while it reaches at most N rows. A larger count answers 409 PreviewStale.
aster.timezone=<zone> The client's time zone, which computed-property formulas read as $timeZone. The name is checked for shape only.
aster.cacheSyncStrategy=<strategy> none, refetch, requestValuesPlusSequences or responseValues. none makes a write answer as return=minimal, unless the request sets return itself.

Unknown Prefer tokens are ignored. A known aster.* token with a malformed value is 400 InvalidRequest.

Not supported

These requests return the status shown. A 501 is NotImplemented, with target set to the option or function, unless the table says otherwise. See Error codes.

Request Status
System query options $search, $compute, $index, $schemaversion, $deltatoken 501
$apply transformations compute, topcount, bottomcount, toppercent, bottompercent, topsum, bottomsum, concat, expand, join, outerjoin, nest, addnested, search and from; custom aggregates (an aggregate without with, or a method outside AsterData); custom transformations; rollup over a named hierarchy 501
$apply grouped by a navigation property itself, or by a path that is not single-valued navigations ending in a property; a hierarchy transformation after an aggregation; $apply combined with $expand; $apply inside $expand 501
$select with a path, nested options or an operation 501
$expand with a reference ($ref), a type cast or a path segment 501
A lambda over a path through a single-valued navigation, or whose body reads the outer entity 501
ancestors or descendants with a $root other than the set itself 501
$filter, $orderby, $select, $expand, $apply or $skiptoken on /$all (only $top, $skip and $count apply) 501
Multipart $batch 501
A $batch member with an if element 424
Nav@odata.bind with an array on a collection-valued navigation 501
A property write through a navigation path 501
A reference through a path of several navigations, or a $ref write through a $batch reference to an entity the same group creates 501
In a $batch group, a nested payload on an entity the group creates, a cascading delete of it, a many-to-many POST, a $ref write, a binding with criteria, or an If-Match other than * 501
A many-to-many reference (the model has no link table) 404
An operation binding whose code the catalog cannot hold 501
A formula or template that must run in the database, where the database cannot run it 501
HEAD on any resource 405
$levels on a navigation that is not recursive 400
$expand option names that are not supported on a navigation 501
A call of an unqualified name that is no built-in function, property or navigation 400 InvalidQuery
A namespace-qualified function the service does not have, or a geo. function 501

Not in the model

A DataSource does not express these types, so they are not in $metadata. A query over them is refused.