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; who may read or change them is on Policy.

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.

Named queries

Every read of stored records is a named query.

Filters

Each where: line is one condition, and a record must meet all of them.

Order and pages

order: lists fields, each with asc or desc.

Counts, sums and groups

A query can count and add up the records it finds instead of returning them.

Children and parents

An include: section adds related records to the result, each under a field of the result type.

A query giving a map layer

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

Every entity gets these operations, called through the entity's name, as Todo.get(todo_id).

When a write is refused

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

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

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

A query or Todo.get inside a for loop is a compile error, because it would read once per item.

One store per action

An action writes to at most one store, counting the public actions it calls.

Where a read comes from

Reads inside an action, policy and authentication always read the store, inside the action's transaction, so they are current.

Reads across domains

A query reads its own domain's entities only, and includes follow references inside the domain.

Reading and writing entities in Redis 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 says which of this works today.

Related