# Save and read a view (/build/views)

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](/catalog/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](/reference/typescript-sdk#create-a-client) shows.

## Create a view [#create-a-view]

[Create a view](/reference/api/views/createView) with a `title` and the settings you need. This one lists images, newest first, grouped by month:



**CLI**

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

**HTTP**

```http
POST /views
Authorization: Bearer <key>
Content-Type: application/json

{
  "title": "Photos by month",
  "query": { "types": ["core.file.image"] },
  "sort": [{ "by": "occurred_at", "direction": "desc" }],
  "group": { "by": "occurred_at", "bucket": "month" }
}
```

**TypeScript**

```ts
const { data } = await marfa.POST("/views", {
  body: {
    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](#read-a-views-items) shows.

## The settings [#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](/build/list-filter-search#filter-by-properties) 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](/build/items-and-types#who-adds-types-where), 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 [#change-or-delete-a-view]

[Update a view](/reference/api/views/updateView) 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:



**CLI**

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

**HTTP**

```http
PATCH /views/<view-id>
Authorization: Bearer <key>
Content-Type: application/json

{ "version": 1, "group": null }
```

**TypeScript**

```ts
const { data } = await marfa.PATCH("/views/{id}", {
  params: { path: { id: viewId } },
  body: { 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](/build/write-safely) 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 [#read-a-views-items]

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



**CLI**

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

**HTTP**

```http
GET /views/<view-id>/items?limit=50
Authorization: Bearer <key>
```

**TypeScript**

```ts
const { data } = await marfa.GET("/views/{id}/items", {
  params: { path: { id: viewId }, query: { 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](/build/write-in-a-working-copy#read-from-the-copy) does. An item missing a sorted field comes after every item that holds it, in either direction.

The rules are in the [views](https://github.com/withmarfa/marfa/blob/main/conformance/spec/views.md) chapter of the contract.
