# Reads and writes

How a program reads and changes stored records: named queries, filters,
order and pages, totals, related records, the operations every entity
gets, what a refused write reports, and how an action stays
all-or-nothing while other requests change the same records. Where
records are stored, and how caches copy them, is on [Entities, stores and migrations](/docs/data.md);
who may read or change them is on [Policy](/docs/policy.md).

The examples follow the golden todo app's `planning` domain: `User`,
`Project` and `Todo`. Each example marked `check` compiles with this
checkout's `jadpo`, and its tests run against PostgreSQL. What isn't built
yet is listed in [What is built](/docs/reads-and-writes-built.md).

| Page | What it covers |
|---|---|
| [Named queries](/docs/named-queries.md) | Every read of stored records is a named query. |
| [Filters](/docs/filters.md) | Each `where:` line is one condition, and a record must meet all of them. |
| [Order and pages](/docs/order-and-pages.md) | `order:` lists fields, each with `asc` or `desc`. |
| [Counts, sums and groups](/docs/counts-sums-and-groups.md) | A query can count and add up the records it finds instead of returning them. |
| [Children and parents](/docs/children-and-parents.md) | An `include:` section adds related records to the result, each under a field of the result type. |
| [A query giving a map layer](/docs/a-query-giving-a-map-layer.md) | A query can return its records as a map layer: a `FeatureCollection<G, P>` (GeoJSON and other formats), where `G` is the geometry type and `P` the type of each feature's properties. |
| [The operations every entity gets](/docs/the-operations-every-entity-gets.md) | Every entity gets these operations, called through the entity's name, as `Todo.get(todo_id)`. |
| [When a write is refused](/docs/when-a-write-is-refused.md) | A write can be refused for two reasons, and a lifecycle transition for a third, when its `when:` doesn't hold (Transitions, above). |
| [All-or-nothing actions and concurrent changes](/docs/all-or-nothing-actions-and-concurrent-changes.md) | Every action is all-or-nothing (Functions and actions): its writes, and those of the public actions it calls, commit together or not at all. |
| [Counters and other one-step updates](/docs/counters-and-other-one-step-updates.md) | When a new value depends only on the stored one, the database works it out in one step and nothing needs checking. |
| [Reading in a loop](/docs/reading-in-a-loop.md) | A query or `Todo.get` inside a `for` loop is a compile error, because it would read once per item. |
| [One store per action](/docs/one-store-per-action.md) | An action writes to at most one store, counting the public actions it calls. |
| [Where a read comes from](/docs/where-a-read-comes-from.md) | Reads inside an action, policy and authentication always read the store, inside the action's transaction, so they are current. |
| [Reads across domains](/docs/reads-across-domains.md) | A query reads its own domain's entities only, and includes follow references inside the domain. |
| [Reading and writing entities in Redis](/docs/queries-on-entities-in-redis.md) ○ not built | An entity in a Redis store (Entities in Redis) is read and written through the same queries and operations as any entity. |

[What is built](/docs/reads-and-writes-built.md) says which of this works today.