Queries
- A filter object inside Entity({ ... }) or Entity[]({ ... }) selects records by field conditions.
- The entity suffix chooses singular, array, or map output independently of the filter.
- Pipe modifiers apply deterministic limits, offsets, ordering, defaults, and access behavior.
Filtered Query Syntax
1need expenses = Expense[]({2 room_id == request.room_id,3 amount > 04})A query uses a filter object inside the fetch parentheses. Separate multiple conditions with commas. All conditions apply to the entity being queried.
Filter Operators
| Operator | Meaning | Example |
|---|---|---|
== | Equal. | room_id == request.room_id |
!= | Not equal. | status != ExpenseStatus.Draft |
>, >= | Greater than or at least. | amount >= 100 |
<, <= | Less than or at most. | amount <= request.maximum |
contains | Substring match; an empty string matches every string. | title contains request.query |
Choosing The Result Shape
1need latest = Expense({ room_id == request.room_id })2 | sort(createdAt, desc)A filtered singular query should match a unique record or provide ordering so the chosen record is deterministic. Array results preserve ordered rows. Map results are keyed by entity identity.
Pipe Modifiers
1need expenses = Expense[]({ room_id == request.room_id })2 | limit(25)3 | skip(25)4 | sort(createdAt, desc)| Modifier | Purpose |
|---|---|
limit(n) | Cap the number of returned records; n is a number literal. |
skip(n) | Offset the result window; n is a number literal. |
sort(field, asc|desc) | Order results by one field and direction. |
| default | Create a missing exact record where stable identity exists. |
| Permission and access modifiers | Apply runtime access checks when the active contract exposes them. |
Permission Checks And Access Bindings
1need receipt = PrivateReceipt(request.receipt_id) ! read| Form | Meaning |
|---|---|
! permission | Require the named runtime permission, such as read, update, or delete, for the fetched record. |
| access: binding | Bind the resolved access information under a local name supplied by the need declaration. |
Access syntax follows the fetch expression. The entity must participate in the active access contract, commonly through an @access entity declaration. Permission names and the bound access value are runtime-contract data; do not invent fields on the access binding.
Indexes And Query Intent
Fields used frequently for filtering, ordering, or joins should follow the entity’s storage contract. In the room model, room_id is indexed because almost every expense query starts from the room.
1entity Expense {2 room_id: string @index3 payer: User4 title: string5 amount: number6}In the current App Marché runtime, exact string and boolean equality and numeric equality or ranges can be pushed to storage. contains, !=, and non-equality comparisons on system id are residual filters. id == value has an exact-id fast path; id > cursor is not an indexed seek. @index makes a field eligible for documented lookup paths, but does not by itself guarantee a particular complexity or bounded scan.
Common Mistakes
| Wrong | Correct |
|---|---|
Expense.find({ ... }) | Expense({ ... }) or Expense[]({ ... }) |
| SQL where/select syntax | Use a Nenu filter object. |
Product[](ids) | map | Product{}(ids) |
| Ambiguous singular filter | Use a unique predicate or deterministic sort. |