# Items, edges and tables (/reference/swift-sdk/items)

Read, search and write the items, edges, tags, extensions and table rows a working copy holds.



A working copy answers reads from its store with no request, and **queues every write**, which shows in the copy at once and reaches the server on the next [drain](/reference/swift-sdk/queue). Each write returns its `QueuedWrite`. The parts are `copy.items`, `copy.edges`, `copy.tags`, `copy.metadata`, `copy.extensions` and `copy.tables`. [Write in a working copy](/build/write-in-a-working-copy) explains the model.

## Read items [#read-items]

| Call | Answers |
| - | - |
| `items.list(_ ListFilters, sort:)` | `Rows<Item>`, the held items the filters select. |
| `items.get(_ id)` | `Item?`: `nil` for an item in the bin or not held. **Throws `hydrationIncomplete`** while a hydration fills the copy. |
| `items.get(_ ids, includingBin:)` | `Rows<Item>`, each held item once, in the order named, from one snapshot. It answers `.partial` during a hydration instead of throwing. |
| `copy.search(_ text, filters:limit:)` | `Rows<SearchHit>`, each with `item`, `score` and `snippet`. `limit` defaults to 20. |
| `items.links(in:)` | `BodyLinks`: each link and embed in the body, and what it names. Takes one ID or a list. |
| `items.displays(of:)`, `items.displays(for:)` | An `ItemDisplay` for each item: `name`, `nil` where the server says "Untitled", and `preview`, at most 240 characters. |
| `items.linkCandidates(of:in:)` | For each `[[link]]` target being typed, its `LinkState` and the held items it could name. |
| `linkParts(in:)` | A free function: every `[[link]]` in a text, with the range of each part in UTF-16 units. |
| `items.thumbnail(_:)` | The held row's `Thumbnail`, with no request. |
| `items.original(ofConflictedCopy:)`, `items.conflictedCopies(of:)` | The two ends of a conflicted copy's `derived-from` edge. |
| `copy.counts(of:_ Counted)` | An `ItemCount` for each ID. |

An `Item` has the fields the API gives it, with `title` and `body` read from the type's fields. Two are the copy's own:

* **`readOnly`** is the server's advice that the item can't be edited, such as an item a connector owns. **Neither the server nor the copy refuses a write for it.** The copy asks again at the end of a catch-up and when a held stream reaches the head, at most once every 15 minutes, so the value can be older. An item the server hasn't answered yet holds `false`.
* **`unreadableProperties`** says why `properties` is empty where the store holds a row the copy can't read. A hydration replaces it.

### Filters [#filters]

`ListFilters` and `SearchFilters` share `types`, `states`, `allStates`, `tier`, `tags`, `occurredAfter`, `occurredBefore`, `filter` and `beneath`. A list adds `source`, `updatedAfter`, `updatedBefore`, `limit` and `offset`.

| Filter | Rule |
| - | - |
| `types` | **Up to ten**, each with its subtree. Empty, more than ten, or a type the copy doesn't hold is refused. |
| `states` | `nil` is active only. `[.trashed]` lists the bin from the copy, newest first. Empty, or beside `allStates`, is refused `validationError`. |
| `filter` | The server's listing grammar, refused where the server refuses it. **A `backref` term is refused `invalid`.** |
| `beneath` | An item and everything it reaches along `parent-of`, as far as the copy holds. |
| `updatedAfter` | Orders by update time, oldest first. A `sort` naming another order is refused. |

`Sort(field:direction:)` takes `.createdAt`, `.updatedAt`, `.occurredAt` or `.property(name:)`. The default is `createdAt` descending. Ties go by ID. [List, filter and search](/build/list-filter-search) has the grammar.

### Counts [#counts]

`Counted` is `.edge(edgeType:)` for items linking in, such as a collection's members, `.backref(edgeType:)` for items linked out to, such as `parent-of` children, or `.rows(table:)`.

* Each `ItemCount` has `total`, `statusGroups` (`nil` for rows) and `held`, which says the copy answered. **Only active items count.**
* The copy asks its server for what it can't be sure of, 100 IDs to a request.
* Where neither can answer, it throws `CountError.unavailable(cause:)`. **Show no count, never 0.**
* A call during `use(_:)` throws `keyChanging`.
* `Server.itemCounts(of:_:)` asks the server directly, for an app with no copy.

`copy.catalog.statusGroup(of:)` gives an item's `StatusGroup`: `.notStarted`, `.inProgress`, `.completed` or `.canceled`.

## Write items [#write-items]

```swift
let write = try await copy.items.create(Draft(
    type: "core.bookmark",
    properties: ["title": "Tide tables", "url": "https://tides.example.com/harbor"],
    tags: ["coast"]))

let bookmark = try await copy.items.get(write.itemId!)!
try await copy.items.update(bookmark.id, Edit(properties: ["title": "Tide tables, harbor"], baseVersion: bookmark.version))
```

| Call | Queues |
| - | - |
| `items.create(_ Draft)` | A create. **Each tag is a write of its own**, `addTag`. |
| `items.update(_:_ Edit)` | An update. **Throws `invalid` unless `baseVersion` is the version the copy holds**, before anything is queued. |
| `items.updateAsRead(_:_ Edit)` | An update based on an older version, which the server merges against what was read. Use it for an editor that held a row while the copy caught up. It takes version `0` for an item this copy created, once the server has answered the create. |
| `items.delete(_:)` | A move to the bin. |
| `items.restore(_:)` | A restore. An item the copy doesn't hold, such as one from the server's bin, is held once the server answers. |
| `items.transition(_:to:)` | A change of `ItemState`: `.active`, `.archived`, `.trashed` or `.revoked`. |

`Draft` takes `type`, `properties`, `tags`, `tier`, `state`, `id`, `source`, `sourceId`, `occurredAt`, `captureLatitude`, `captureLongitude` and `edges`.

`Edit` takes `properties`, `replaceProperties`, `clearProperties`, `baseVersion`, `sourceId`, `type`, `tier`, `occurredAt` and `clearOccurredAt`:

* **A `null` in `properties` clears nothing.** Name a property in `clearProperties` to remove it.
* `type` moves the item to another type.
* `clearOccurredAt` beside `occurredAt` is refused.

**The copy checks properties against the type before it queues.** A value of the wrong kind throws `validation` with the code `invalid_properties`.

### The bin [#the-bin]

| Call | Does |
| - | - |
| `items.bin(type:after:limit:)` | One `BinPage` of the server's bin, read online whatever the slice. `limit` is held to 1 through 100. A short page can still have a `nextCursor`. |
| `items.purge(_:version:)` | **Destroys an item in the bin on the server now.** Never queued, so it needs the server. |

`purge` is sent at `version`, or at the version the copy holds, so an item changed since throws `versionConflict`. Before sending, it throws:

* `notFound` with `not_held`, for an item the copy doesn't hold and no `version`.
* `validation` with `invalid_transition`, for an item the copy shows outside the bin.
* `invalid`, for an item with a write still waiting.

Offline it throws `network`, and with no server `noServer`. The key needs `items.purge`.

## Edges [#edges]

| Call | Does |
| - | - |
| `edges.from(_:)`, `edges.to(_:)` | The held edges at one end of an item, unsent ones included. |
| `edges.ofType(_:)` | Every held edge of one type, oldest first. |
| `edges.get(_:)` | One edge, or several in the order named. |
| `edges.create(from:to:type:properties:id:)` | Queues an edge. |
| `edges.check(from:to:type:properties:id:)` | Throws what `create` would throw now, and queues nothing. |
| `edges.update(_:_ EdgeEdit)` | Changes properties, moves one end, or both. **Returns `nil` and queues nothing** for an edit that changes nothing. |
| `edges.check(_:moving:)` | Throws what a move would throw now. A move onto the end the edge holds returns. |
| `edges.delete(_:)` | Queues a delete. |

Every edge read and write **throws `hydrationIncomplete` until the copy is whole**: during a hydration, and while a stale copy refills.

An `Edge` has `fromId`, `toId`, `edgeType`, `properties` and `version`. A queued edge write names its from end in `itemId` and its to end in `toId`.

`EdgeEdit(_ properties:baseVersion:move:)` moves one end with `.from(_ id)` or `.to(_ id)`. Each property given replaces its whole value.

* **A move of the from end expires the copy** once the server accepts it. The drain sends the writes behind the move, then throws `copyExpired` with `reach_changed`, and the app hydrates again.
* A move of the to end doesn't expire the copy.
* A move to an item whose create is still queued waits for that create.

### Refusals [#refusals]

`create`, `check` and a move refuse **in the server's order, with the server's code**, judged from what the copy holds:

| Refusal | Error and code |
| - | - |
| An edge from an item to itself | `validation`, `edge_cycle` |
| An end in the bin | `notFound`, `item_not_found` |
| An end of a type the edge type doesn't admit, then nesting under a flat type | `validation`, `edge_constraint_violation` |
| The same type, from end and to end as an edge the copy shows | `edge_constraint_violation`, `details.constraint` is `"duplicate"` |
| An end that already holds its one edge of the type, such as a second `parent-of` parent | `edge_constraint_violation`, `details.constraint` is `"cardinality"`, with `details.from_id` or `details.to_id` |
| A cycle through held edges | `edge_cycle` |
| A move where the end that stays may hold more than one edge, such as `about` | `validation_error` |

```swift
do {
    try await copy.edges.check(from: note.id, to: note.id, type: "references")
} catch MarfaError.validation(let code, _, let details, _) {
    // code is "edge_cycle", details is ["edge_type": "references"]
}
```

**Returning isn't the server's verdict.** Where the copy doesn't hold what decides a refusal, such as a cycle outside its slice, the check returns and the queued write meets the server. A type's `writtenFrom` says which end an edge is written from (`EdgeWrittenFrom` is `.from`, `.to` or `.none`). [Edges in a working copy](/build/edges-in-a-working-copy) covers drag and drop.

## Tags and extensions [#tags-and-extensions]

| Call | Queues |
| - | - |
| `tags.add(_:to:)` | One tag, leaving the others. An item that would hold **more than 100 tags** throws `validation_error`, and earlier adds stay queued. |
| `tags.remove(_:from:)` | One tag's removal. |
| `metadata.replaceTags(of:with:)` | Every tag in one write. |
| `extensions.write(_ namespace:_ body:on:)` | An extension's whole body. |
| `extensions.delete(_ namespace:from:)` | An extension's removal. |

## Tables [#tables]

An item of a type that declares a table, or one carrying its own `columns`, has rows in it. **A row is never an item**: it has no version, tags or edges. The copy holds a table **whole or not at all**, and reads one it doesn't hold from the server. [Tables](/build/tables) explains them.

| Call | Does |
| - | - |
| `tables.hold(_ table:ofType:)` | Holds that table of every held item of the type, or a pattern of types, and fills it. Returns `TableHold` with `wasHeld` and `fill`, which is `nil` where another call holds the stream and fills it. Throws `invalid` for a table no such type declares. |
| `tables.letGo(_:ofType:)` | Drops the choice, and the rows no other choice holds. **Queued writes stay queued.** |
| `tables.held()` | `HeldTables`: the `choices`, and each held table's `state` and `rows`. |
| `tables.fill()` | One pass over the tables not yet whole. `TableFill` counts `whole`, `online`, `unfilled` and `failed`, with the last `failure`. |
| `tables.rows(of:in:_ RowsQuery)` | `TableAnswer<TableRowPage>`, with `rows` and `nextCursor`. |
| `tables.row(_:of:in:)` | One `TableRow`. Throws `notFound` for a row the table doesn't hold. |
| `tables.totals(of:in:filter:)` | `TableTotals`: `rowCount`, and each adding column's `sum`, `count`, `average`, `min` or `max`. |
| `tables.write(_ [RowOperation]:to:of:)` | Queues one batch and shows it at once. |
| `tables.undo(batch:in:of:)` | Queues the undo of a batch the server took. **No row changes until the server's event arrives.** |

`TableState` is `.owed`, `.filling`, `.whole`, or `.online` for a table past the cap on rows a copy holds. **A `TableAnswer` sets `held` when the copy answered it**, with waiting writes laid over the rows. Otherwise the server answered, which a copy offline can't reach. **Before each such request, the copy checks that the server is the instance it was built from.** If another instance answers at the address, the read throws `copyExpired`, the copy expires, and no item ID is sent. A lookup of a linked item by ID is checked the same way.

`RowsQuery` takes `limit` (1 through 1,000), `cursor`, `filter` (the item grammar, with `values.<column>`, `id` and `updated_at`), `sort` (`.id`, `.updatedAt` or `.column(_:)`) and `direction`. A `TableRow` has `id`, `values`, `updatedAt` and `withheld`, the columns naming an item the key can't read.

`RowOperation` is `.put(id:values:)`, which writes the whole row, `.patch(id:values:)`, where `null` clears a column, or `.delete(id:)`.

* **The server takes all of a batch or none of it.** A drain sends consecutive batches to one table in one request, each with its own verdict: `accepted`, `conflicted` with the replaced cells in `conflicts`, or `refused`.
* The accepted write's `rowBatch` is the batch to pass to `undo`.
* `write` throws `notFound` with `item_not_found` or `table_not_found`, or `validation`, and queues nothing.

A held table is read and written offline. Changed tables arrive in `Reread.Parts.rows.tables` and `CatchUpReport.changedTables`, and a stream hears `.refreshed(.tables)`. The rules are in the contract's [tables](https://github.com/withmarfa/marfa/blob/main/conformance/spec/tables.md) chapter.
