---
title: Views
description: A view is a saved set of filters, a sort and columns over one record type. Definition views, agent-proposed views and people's views share one shape.
sidebar:
  order: 14
---

## What it is

A view is a named way of looking at one record type: which records (filters, status, time window), in what order (sort), with which columns. Hiring Signals ships three: New roles, Dropped by settings, and Hiring companies.

## Why it exists

People look at the same slices again and again. A view saves the slice once. Because definition views, agent views and people's views share one shape, the Desk renders them all the same way, and a routine can suggest a view without being able to change one a person made.

## How it works

### Three sources

| Made by | Stored | Who can change it |
|---|---|---|
| The definition | `meta/definition` `views` (with `madeBy: "definition"`) | Nobody on the Desk; built-in views are read-only |
| The agent | `views/<id>`, created as `state: "proposed"` in the summary phase, only if absent | People, from then on; the agent can never edit or delete it |
| People | `views/<id>` | People |

### Filters

`filters` may hold `q` (text), `status` (`all`, `active`, `dropped`), `starred`, `tag`, `source`, `reason`, and `fields`, which maps a declared field to the one value it must equal, for example `{"market": "AU", "remote": "true"}`. A field filter at the top level of `filters` is a lint error.

`window` is `all`, `week`, `month` or `last-month`. `sort` is `{field, dir}` with `dir` `asc` or `desc`. `group` is a field name. Besides declared fields, a view may name the meta fields `lastSeen`, `firstSeen`, `seenCount`, `status` and `dropReason`.

### Agent columns

A producer can also propose a column, `columns/<id>`, created once and then owned by people. Its values travel on records as `agentFields`.

> Since 0.5.0: saved views are shared with everyone on the Desk, and only the creator (the view's `madeBy`) can rename, reorder, delete or update one. Others can Duplicate. New views also write `createdAt`. Pin is per viewer at `data/users/<viewer>/state/pin/<viewId>`. A "modified" marker appears when filters differ from the saved view. Views nest under their type in the sidebar. Agent, definition and pre-0.5.0 people's views stay editable by anyone who can write. The ownership rule is enforced in the Desk only: the store's rules cannot express per-document ownership on a shared path.

## Worked example

Hiring Signals' "Dropped by settings" view:

```json
{
  "id": "dropped-roles",
  "type": "role",
  "name": "Dropped by settings",
  "filters": {"status": "dropped"},
  "sort": {"field": "lastSeen", "dir": "desc"},
  "columns": ["title", "company", "market", "dropReason"]
}
```

A person wants Australian remote roles only. On Browse they filter `market` to AU and `remote` to true and save the view "AU remote". The Desk writes `views/au-remote` with `filters: {"status": "active", "fields": {"market": "AU", "remote": "true"}}`.

## Reference

| Field | Notes |
|---|---|
| `id` | Slug |
| `type` | A declared type |
| `name` | Shown in the nav and view menu |
| `filters` | `{q, status, starred, tag, source, reason, fields}` |
| `window` | `all`, `week`, `month`, `last-month` |
| `sort` | `{field, dir}` |
| `group` | A field name |
| `columns` | Declared fields and meta fields |
| `madeBy` | `definition`, the agent, or a viewer id |
| `producer` | The producer that declared or proposed it |
| `state` | `proposed` for agent views |

`definition.lint_view` checks the shape for all three sources.

## Common pitfalls

- **Editing a built-in view.** Built-in views are read-only. Save a copy.
- **A field filter outside `fields`.** `{"filters": {"market": "AU"}}` fails lint. Use `{"filters": {"fields": {"market": "AU"}}}`.
- **Agent views piling up.** An agent view is created only if absent, so it appears once. People can delete it; the agent will not recreate one with the same id while it exists, and cannot delete it.

## Related

- [The Desk: Views](/desk/views)
- [The definition](/concepts/definition)
- [Definition schema reference](/reference/definition-schema)