When to use these helpers
Use this helper in a reviewed document template when the supplied record context is insufficient. Keep lookup scope small and test in the selected execution mode.Calling style
Call a helper asgetRecords({ entityKey: "service_requests", limit: 5 }). Not every helper is available everywhere: validation, form, and document-template helpers have distinct context contracts. Editor suggestions are not proof that a helper is supported at runtime.
Complete function reference
getRecords
Looks up records while rendering a document template. Each call clamps limit to 1–500; caller and admin execution modes have different data access behavior.
Signature: getRecords({ entityKey, q?, filters?, limit?, sorting?, search? })
Example:
Query contract and access boundaries
Request and result shape
getRecords requires an object with a non-empty entityKey; passing text or an object without an entity key makes rendering fail instead of guessing. The limit defaults to 100 and is clamped to the inclusive range 1–500. When filters is omitted, the helper uses an empty list. If q is omitted, KayanOS selects the normal document-record shape, including data:* and stable record metadata such as id, label, creation, and update timestamps.
When a custom q includes data:*, KayanOS flattens data values into each result row so you can write row.request_reference. A custom query without data:* retains the query result shape; do not assume fields are at the top level in that case. Pass sorting as an array, not a single object:
search and q when the need is understood and testable. Start with one entity, one filter, and a small limit; do not turn a template loop into an unreviewed broad query.
Caller mode and administrative mode
In caller mode, the lookup runs as the member rendering the document and applies that member’s record-read permissions. In administrative mode, the lookup uses the administrative data path; rendering in that mode itself requires Builder access and an assigned administrative verb. Do not make administrative mode the default just because a caller-mode lookup returned no rows. A non-empty allowed-entity list restricts administrative lookups to the listed entity keys. An omitted or empty administrative allowed-entity list is broad administrative access, not deny-all. When administrative mode is approved, set a short non-empty list, test that a lookup outside it fails, and retain a clear approval reason with the template.Safe worked example
For a short list of approved citizen-service requests inside a review letter, use a small explicit loop, then test output in each intended execution mode:Before you publish
- Start with a known value and confirm the expected result.
- Handle null, empty text, and empty lists deliberately.
- Do not place secrets, access tokens, or sensitive personal data in an expression.
- Read expression contexts and availability before copying an expression between features.
