Save and read a view

Save a query, a sort and a grouping as a view that every app lists the same way, change or delete it, and read its items from the server.

A view saves a listing so every app shows the same one. Its query says which items it lists, and its sort and group say in what order and how they group. How an app draws the items is the app's own, so a view holds no layout. In the TypeScript examples, marfa is a client made as the TypeScript SDK shows.

Create a view

Create a view with a title and the settings you need. This one lists images, newest first, grouped by month:

marfa views create --title "Photos by month" \
  --query '{"types":["core.file.image"]}' \
  --sort '[{"by":"occurred_at","direction":"desc"}]' \
  --group '{"by":"occurred_at","bucket":"month"}'

The answer is the view as a system.view item at version 1. It holds no items: read them as Read a view's items shows.

The settings

  • title is required, up to 500 characters.
  • query says which items the view lists: types (up to 100, each with the types beneath it), state, tier, a filter as List, filter and search describes, and beneath, an item and everything under it by parent-of.
  • sort is up to 10 keys of by and direction, applied in turn. A by is title, created_at, updated_at, occurred_at, last_activity_at, type, state, tier, tags or properties.<name>. A view with no sort lists the newest occurred_at first.
  • group has a by from the same fields except last_activity_at, which only sorts, or edge[<type>] or backref[<type>]. A bucket of day, week, month or year groups a date by period, order puts chosen groups first, and hidden leaves groups out.

A view never lists items of a hidden type, under system or app, and a query that names one is refused. It never widens access: each app sees only the items its own credential reaches.

Change or delete a view

Update a view with the version you read and the settings you change. Each setting you name is replaced whole, and null clears group, the one setting that takes it:

marfa views update <view-id> --version 1 --group null

A change sent at an older version still applies when nobody has changed the same setting since. Otherwise Marfa answers 409 version_conflict, with conflicting_fields and current: read it, decide, and send again at the new version, as Update items without losing changes shows. marfa views delete removes a view at once, with no bin. A view that sits under an item by parent-of is revoked when deleting that item cascades to it: the view still reads and deletes, and a change or a read of its items is refused 400 invalid_transition.

Read a view's items

Writing a view needs write on system.view, and reading one needs read. Ask for a page of the items it lists:

marfa views items <view-id> --limit 50

The answer holds the items in the view's order and a next_cursor: stop only when it is null, and --all follows it for you. A page holds 50 items, or 1 to 200 if you ask. The server lists only what the credential can read, no hidden items, and no groups: the app groups the items, or a working copy does. An item missing a sorted field comes after every item that holds it, in either direction.

The rules are in the views chapter of the contract.

On this page