> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document-template lookup helper

> The document-template-only record lookup contract, including its object argument and caller/admin execution differences.

## 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 as `getRecords({ 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:**

```txt theme={null}
getRecords({ entityKey: "service_requests", filters: [["status", "eq", "approved"]], limit: 20 })
```

**Availability:** Document templates only; function call only. Keep the query narrow and test it in the selected caller/admin execution mode.

**Note:** Use this as a function call, not as a transform.

## 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:

```txt theme={null}
getRecords({
  entityKey: "citizen_service_requests",
  filters: [["status", "eq", "approved"]],
  limit: 10,
  sorting: [{ field: "created", direction: "desc" }]
})
```

You can also pass `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:

```txt theme={null}
{{#each getRecords({
  entityKey: "citizen_service_requests",
  filters: [["status", "eq", "approved"]],
  limit: 5,
  sorting: [{ field: "created", direction: "desc" }]
}) as row}}
{{ row.request_reference }} — {{ row.service_type }}
{{/each}}
```

Read [document-template expression context](/reference/expressions/document-template-context) and [Document-template tags and rendering](/build/document-template-tags-and-rendering) before publishing a template that performs a lookup.

## 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](/reference/expressions/contexts) before copying an expression between features.

![Document-template lookup helper in KayanOS](https://kayanos.app/docs-images/en/reference/expressions-helpers-document-templates.png)