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
titleis required, up to 500 characters.querysays which items the view lists:types(up to 100, each with the types beneath it),state,tier, afilteras List, filter and search describes, andbeneath, an item and everything under it byparent-of.sortis up to 10 keys ofbyanddirection, applied in turn. Abyistitle,created_at,updated_at,occurred_at,last_activity_at,type,state,tier,tagsorproperties.<name>. A view with no sort lists the newestoccurred_atfirst.grouphas abyfrom the same fields exceptlast_activity_at, which only sorts, oredge[<type>]orbackref[<type>]. Abucketofday,week,monthoryeargroups a date by period,orderputs chosen groups first, andhiddenleaves 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 nullA 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 50The 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.