Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Current model-key correction — 8 November 2026. The preserved examples below contain historical camelCase record-type/field keys. Do not copy those keys into the current editor or API: use record type leave_request and the lowercase field keys in the current model worksheet, including request_id, employee_id, manager_id, start_date, end_date, requested_days and decision_comment. Form, rule and case input names are separate declarations; map them explicitly rather than mechanically renaming every input. The preserved body remains historical source material, not a current executable model payload.
DataGrid governed query runtime
Learning path and preparation
Use this guide after a model version has an applied publication and a screen has an authored DataGrid. A grid is a viewport over an authorized, immutable screen node; it is not a public arbitrary-query builder. First select the source in the designer, inspect the selected-source capability response, choose visible columns and a stable row key, and publish the screen. At runtime the browser supplies only view controls. The server reconstructs source identity, model version, publication and field projection from the published node.
Prepare an isolated people-ops teaching workspace, a modeled leaveRequest record type, three synthetic requests and an authorized screen viewer. Nadia is the example builder; Sara is a manager-viewer. Their display names are not account IDs or grants. Replace every sample screen key, node ID, version, model ID and publication with the actual admitted fixture values. The examples below describe supported contracts; no request is executed by this document.
| Runtime input/result | Meaning and practical rule |
|---|---|
version / nodeId |
Exact published screen and authored node. A draft or unrelated node is not a fallback. |
search |
Optional bounded search, accepted only for supported selected-source capability. |
filters |
Declared fields/operators and typed values; a filter cannot add unreadable columns. |
sort |
One declared field and supported direction, not an SQL fragment. |
page |
Zero-based index, bounded size; the applicable route may support an opaque cursor. |
items, page, size, totalItems |
Returned viewport and authorized count; page length is not the total. |
rowKeyField |
Server-chosen stable identity; keep its wire value unchanged. |
capabilities |
What this source can actually page/search/filter/sort, not every catalog possibility. |
The ordinary published-record route is /data-grid-query; a supported QUERY-rule grid uses /data-grid-rule-query. A Repeater uses the separate rule-query-collection contract. Do not transfer one request body, cursor or source marker between them. For connected learning, continue with query-driven application.
Worked examples
Example DATA-GRID-01 — Read the first published leave-grid page
Scenario and inputs. Sara opens a published leave-overview screen at version 3. Its saved node requestsGrid already selects the permitted model, explicit columns and stable key. The fixture contains two visible pending requests and one request stored in a different workspace. The JSON is a complete ordinary grid request body; the example key/version/node must be replaced with the reader’s actual publication.
Procedure. 1. Confirm Sara can open the published screen and the selected source supports the requested operations. 2. Send the body to POST /api/screens/leave-overview/data-grid-query using the normal authenticated workspace context. 3. Render only returned items, retaining rowKeyField values exactly. 4. Use the returned count to build paging controls; do not run an unscoped second query to manufacture totals.
{
"version": 3,
"nodeId": "requestsGrid",
"search": "",
"filters": [],
"sort": {
"field": "requestId",
"direction": "asc"
},
"page": {
"index": 0,
"size": 25
}
}
Expected result. A successful authorized response contains only the selected projection for visible records, its page metadata and source capabilities. If only two records are visible, the other workspace’s third record must not appear in rows or authorized totals.
Failure and recovery. An unavailable publication, denied model, unsupported sort or unknown body property is not an empty dataset. Keep the refusal distinct from zero results, verify the exact screen publication/source capability and have the builder correct and republish the affected node before retrying.
Sources. DataGridQueryController.java, DataRecordReadService.java.
Example DATA-GRID-02 — Keep exact numbers and row identities intact
Scenario and inputs. Nadia adds a separate expense grid with a LONG primary key and DECIMAL amount. Two stored IDs are 9007199254740992 and 9007199254740993; their distinction must survive the browser. The operator has admitted the exact numeric source types and an amount column to the published grid. These example values describe a precision test, not a new public write API.
Procedure. 1. Inspect the selected source’s declared key and amount types before publishing. 2. Read the published grid normally, keeping returned numeric primary-key strings as strings through selection, links and subsequent native actions. 3. For a typed exact filter, use the canonical decimal-string representation required by the request parser rather than a rounded JavaScript number. 4. Compare returned identity and amount independently; display formatting must not rewrite the underlying key.
Expected result. The two IDs remain distinct selections. Exact decimal filtering is evaluated under the declared source contract, and the response does not merge two rows because a client coerced both keys to the same floating-point number.
Failure and recovery. If a client has already rounded an ID or amount, converting that rounded number to text cannot recover the original. Discard the affected client state, reload canonical rows from the authorized server response and fix the coercion before offering an update or delete action.
Sources. DataGridQueryController.java, ScreenWireModule.java.
Example DATA-GRID-03 — Project one permitted related employee field
Scenario and inputs. The leave model relates each request to one employee record. Nadia wants the employee’s display name beside requestId; she does not want a nested collection of all colleagues. The exact published source advertises BOUNDED_ONE_TO_ONE, and Sara can read the terminal name field. Relationship names and cases are taken from source metadata, not inferred from display labels.
Procedure. 1. Open the selected-source metadata and verify the requested relationship is scalar at every hop. 2. Choose the actual dotted field offered by the builder and add it to the explicit column projection. 3. Re-run the selected-source capability check, save and publish the screen. 4. Read a bounded page as Sara and verify missing optional related data is represented according to the source null contract. 5. Keep any filter/sort on that field within the advertised capability.
Expected result. The supported PostgreSQL path emits bounded governed joins within the same page statement. It observes the documented three-hop, twenty-path and eight-join limits; a relation label alone never grants a cross-model read.
Failure and recovery. A one-to-many crossing, cycle, unreadable terminal field or unsupported adapter must fail closed. Model the collection from its child side or expose an admitted flattened/aggregate source; do not bypass the control by sending a hand-built join or SQL expression.
Sources. DataGridQueryController.java, GridQueryTimeouts.java.
Example DATA-GRID-04 — Diagnose a rejected page without guessing a new source
Scenario and inputs. Nadia copies a valid grid request while troubleshooting and accidentally adds sql inside page. Sara also has an older browser tab pointing to a screen version whose node has since been changed in a newer publication. This example concerns contract refusal and version selection; publishing a newer screen does not silently rewrite an older immutable screen document.
Procedure. 1. Retain the exact version and node from the failed request. 2. Compare the body with the closed request fields and nested page/filter/sort contracts. 3. Remove the unsupported property from the client implementation, keeping the original source and intended viewport. 4. Decide explicitly whether the user should open the original supported publication or a newly published version, then reload through normal navigation. 5. Check the result under the same actor’s authorization.
Expected result. The malformed page body is refused before it becomes an arbitrary provider query. Correcting the client restores only the supported viewport; it does not expand selected fields or choose the newest available model automatically.
Failure and recovery. A repeated refusal after correcting the body can indicate an unsupported source, missing stable row keys or an unavailable pinned publication. Inspect the exact owning source and safe server diagnostic; do not turn a failed page into a successful-looking empty response or issue a broader unauthorized catalog request.
Sources. DataGridQueryController.java, DataRecordReadService.java.
Detailed reference
DataGrid uses an immutable published-screen contract. Studio obtains modelId,
recordTypeKey, sourceVersion, and primaryKeyField directly from
GET /api/rules/record-types; it must not parse the legacy sourceKey.
The catalog deliberately reports conservative dataGridCapabilities with
supported=false. After the user selects a source, Studio calls:
GET /api/data-models/{modelId}/versions/{version}/record-types/{typeKey}/grid-capabilities
This selected-source preflight requires DATA_MODEL_VIEW and checks the exact
applied publication/version for the current actor. Unknown, unavailable, or
provider-failed sources return available=false with a fixed safe reason.
Studio keeps Apply disabled unless available=true and enables search/filter/
sort only from the returned flags.
Published nodes persist exactly:
{"kind":"published-record-type","modelId":"...","version":1,"recordTypeKey":"Order"}
Unknown properties are rejected until the source-reference contract is
versioned to include them. The node also persists rowKeyField from the
catalog's primaryKeyField and an explicit column projection.
Runtime queries use:
POST /api/screens/{screenKey}/data-grid-query
The request contains only published screen version, node id, scalar filters,
search, sort, and page. The server reloads the published node and pinned applied
data-model version, requires SCREEN_VIEW then DATA_MODEL_VIEW, derives the
source/projection/identity from server-owned documents, and pushes supported
operations into the source. Results are re-projected and duplicate/missing row
keys fail the whole page.
The JSON contract rejects duplicate keys and unknown nested filter, sort, or
page properties. Use canonical decimal strings for full-range LONG and exact
DECIMAL filter values. Numeric primary keys are returned as canonical decimal
strings so browser number precision cannot merge two row identities; other
numeric cells retain their declared values.
PostgreSQL queries use a 15-second statement timeout. Page rows, exact total, and the 2 MiB database-side byte gate are evaluated in one statement snapshot. If the page exceeds the gate, only a bounded rejection sentinel crosses JDBC.
Modeled-record PostgreSQL sources support governed dotted scalar columns such
as order.customer.name when every hop is one-to-one and the source declares
BOUNDED_ONE_TO_ONE relationship capability. The server resolves exact
case-sensitive schema identities and emits bounded, quoted joins in the same
statement; fields, predicates, and search values remain server-owned or bound
parameters. Traversal is limited to three relationship hops, twenty distinct
paths, and eight joins. One-to-many crossings, cross-source relationships,
cycles, excessive depth/joins, unreadable terminal fields, and adapters without
the capability fail closed. A collection must instead be queried from its child
record side or exposed by a governed flattened/aggregate view.