Updates and live queries
Keep a working copy following its server, and keep an app's screens current as the copy changes.
A working copy follows its server's events only while the app holds a stream: updates() for an app that shows the copy, or changes() for code that needs each change as it happens. LiveQuery builds on updates() to keep one read current in SwiftUI.
| Call | Gives | Use it for |
|---|---|---|
LiveQuery(_:reading:) | An @Observable value that rereads itself | A SwiftUI screen |
updates() | CopyUpdates, coalesced, with the connection | An app's own read model |
changes() | AsyncStream<Change>, every change uncoalesced | Logs, tests and code reacting to one kind of change |
changes(since:most:) | CopyChanges, what changed since a cursor | Rereading only what changed after a relaunch |
Live queries
@State private var recent = LiveQuery(copy, reading: .list(ListFilters(types: ["core.file.image"])))
var body: some View {
List(recent.value, id: \.id) { item in Text(item.title ?? "Untitled") }
}LiveQuery is a @MainActor class. It reads at once, then reads again after each update that could change its answer, and holds a stream while it lives, so the copy follows its server.
| Property | Holds |
|---|---|
value | The last successful answer, or the reading's placeholder before one. |
isLoading | Whether a read is running, from creation until the first read ends and during each later one. |
error | Why the last read failed, nil after one succeeds. value keeps the last good answer. |
connection | The copy's connection, .connecting until the first update. |
reading | What it reads. Assigning it starts a new read at once and drops any read still running. |
refresh() reads now and returns after a read that began after the call.
A Reading is a read and its placeholder. Make your own with Reading(placeholder:_:), or use one of these:
| Reading | Value |
|---|---|
.list(_:sort:) | Rows<Item> |
.search(_:filters:limit:) | Rows<Item> |
.item(_:) | Item? |
.queue | [QueuedWrite] |
.views | Rows<SavedView> |
.view(_:) | SavedView? |
.list(inView:limit:offset:) | Rows<Item> |
.groups(inView:timeZone:) | Rows<ViewGroup> |
Rows is a collection of the rows with a completeness: .complete, .partial while a hydration fills the copy, or .stale while a stale copy refills.
Copy updates
for await update in copy.updates() {
switch update.reread {
case .everything: await reloadAll()
case .parts(let parts): await reload(parts)
}
show(update.connection)
}The first update asks to read everything and gives the connection. Each later one names what changed since the one before. At most one update waits while the app reads, holding every pending change. Iterate a sequence once; ask again for another consumer.
CopyUpdate field | Holds |
|---|---|
reread | .everything, or .parts(Parts). |
connection | What the copy is doing with its server. |
fill | A running hydration's progress, listed against expected, with fraction. Read every half second. |
lastSynced | When the copy last finished a pull, as Status.lastSynced says. |
Reread.Parts names what to read again. Anything it doesn't name is unchanged.
| Part | Read again |
|---|---|
rows.items, rows.removedItems | Items held, and items no longer held. Read the held ones with items.get(_:includingBin:); one missing from the answer went to the bin. |
rows.edges, rows.removedEdges | Edges held, and edges no longer held. |
rows.tables | Each held table whose state or rows changed, as itemId and table. |
queue | queue.all(). |
views | items.views(), after this copy wrote a view. A view another device writes arrives in rows.items. |
catalog | copy.catalog. |
An update carries .everything when more than 1,000 items, 1,000 edges or 1,000 tables changed, and during a hydration as rows arrive. An update can carry no reread when only its connection, fill or lastSynced changed.
The connection
CopyConnection | Means | What the copy does |
|---|---|---|
.connecting | Asking the server, as updates begin, after use(_:), or while a stale copy refills. | Waits for an answer. |
.following | The server answered and the copy follows its events. | |
.offline(error) | A failure that may mend itself, such as the network or a server error. | Retries after 5 seconds, doubling to 5 minutes, never sooner than a rate limit's retryAfterSeconds. |
.stopped(error) | An error that asking again may not clear, such as a refusal, a store fault, noCatalog or wrongServer. | Tries a catch-up every 5 minutes. |
.keyRefused(error) | The server refused the key or sign-in. | Nothing until use(_:). |
.needsHydration(error) | The copy must be hydrated first: it expired, changed instance or never completed a hydration. | Nothing until the app hydrates. |
.local | No server, or a reader watching the writer's saves. | |
.closed | The copy was closed. It is the last update. |
Only a catch-up or a hydration that succeeds, the app's or a retry's, makes a stopped or offline copy .following. An error the app's own arguments caused, such as invalid or validation, doesn't change the connection. While a sequence is held, a drain that left writes undelivered is made again after the same waits.
Change streams
changes() tells each change as it happens. Each Change has an origin, and itemId and edgeId where one row is named.
Change.Origin | Means |
|---|---|
.local(WriteKind) | The app queued a write of this kind. |
.server(event:cursor:) | The copy applied a server event, such as item.updated. With no itemId, rows' readOnly changed: read the copy again. |
.serverUnreachable(error) | The follow can't reach the server. Told once, however many fail. |
.serverReachable | A request reached the server again. The held stream drains the queue itself. |
.queueDrained(DrainReport) | That drain ended, after each write's .answered. |
.queueNotDrained(error) | That drain stopped. Answers it recorded stay recorded. |
.answered(DrainVerdict) | A drain answered this write. |
.saved(dataVersion:) | The writer saved; a reader reads again. A new stream on a reader hears one first. |
.refreshed(Refresh) | Many rows may have changed at once. |
.stopped(error) | What fed the stream stopped. Local writes are still told. |
Refresh says why: .hydrated, .unfinished (a hydration failed part way; its rows stay), .caughtUp, .drained, .withdrawn, .forgotten, .pinned, .unpinned, .purged, .folderWritten, .viewWritten, .catalog or .tables.
A stream that stops stays stopped until the app's next hydration or catch-up, or until a stream is asked for while none is held. Streams are told .stopped when the follow fails with an error other than the network, and when a stale copy can't refill in place: instanceChanged, or copyExpired with reach_changed, slice_changed, head_past_log, not_stale, or catchup_too_old for a copy that was already stale as the follow began.
A copy that falls behind
When the server's event log lets the copy's cursor go, as it can while a Mac sleeps, the copy refills itself over the slice it holds, keeping every row, queued write and file, and tells .refreshed(.hydrated). A refill the network or server fails is told .refreshed(.unfinished) and tried again after 1 second, further apart each time, up to 5 minutes apart. It refills only while the key is the one the follow used.
Read only what changed
changes(since:most:) answers what changed in the copy since a ChangeCursor:
.named(ChangedRows, next:)lists the rows to read again and drop, asReread.Parts.rowsdoes..everything(next:)asks for the whole copy to be read again: with no cursor, one from another store or from before a change to the types, or when more thanmost(default 1,000) rows changed in one category.
Keep next.rawValue across launches. Keep the cursor you passed until you have read what the answer names. The call throws hydrationIncomplete while a hydration is part way or the copy is stale. An item whose body links resolve differently only because another item changed isn't named, so an app that shows links reads items.links(in:) again for the rows it shows.
The rules are in the contract's device chapter, and Keep in sync explains following a server.