Your first chart, step by step.

1 notes

Start with notes that have properties.

A chart draws properties, so the first step happens in your notes. Each book is one note, and its frontmatter holds the facts about it: who wrote it, the genre, how long it is, whether you finished it.

---
type: book
author: Frank Herbert
genre: sci-fi
pages: 412
rating: 5
status: finished
started: 2025-04-30
finished: 2025-05-09
---

• Use the same property names in every note: genre, not Genre in one and category in another.
• Write numbers as numbers (412) and dates as YYYY-MM-DD, so Obsidian types them and the chart can do maths.
• A property like type: book makes the notes easy to pick out in the next step.

Follow along: download the starter and unzip it into the root of a vault. You get a Reading folder with the 26 book notes (made up, from Agate's demo vault), plus the files for the next steps. Or browse the notes on GitHub.

2 base

Let a base pick the notes.

A base is Obsidian's query over your notes: a filter, the columns to show, a sort. Create one with New base from the file menu, or open Books.base from the starter. Here it keeps every note with type == "book".

filters:
  and:
    - type == "book"
views:
  - type: table
    name: Shelf
    order: [file.name, author, genre, pages,
            status, started, finished, rating]
    sort:
      - property: started
        direction: DESC

You rarely write this by hand: Filter, Properties and Sort in the toolbar write it for you. Every column you can show is a field the chart can draw, named by its property id: note.genre, note.pages, file.name.

The file: Books.base on GitHub. The demo vault's richer version is Reading.base.

3 chart

Add a chart view.

In the base, open the view menu and Add view, then set its layout to Agate chart. The empty view offers two ways in.

With a recipe

1. Click Pick a recipe and choose Notes per category.
2. Set Category to genre and Color by to status.
3. Keep the file name bars-genre.vl.json and click Create chart.

Agate writes the spec into charts/ and points the view at it. The chart appears straight away.

Or with an assistant

Click Copy prompt for an LLM. The prompt holds your base's properties, a few sample notes and the rules a working Agate spec follows. Paste it into any assistant, describe the chart in plain words, save the reply as a .vl.json file and pick it as the view's Spec file.

I use Obsidian with the Agate plugin, which renders
Vega and Vega-Lite specs over an Obsidian Bases view.
Write a chart spec for me.

## What I want
Books per genre as horizontal bars, colored by status.

## Data
The spec receives the notes of an Obsidian base
(view "Shelf"), 26 notes, as a dataset named `base`.
…
Properties in this base:
- `note.genre` (text)
- `note.pages` (number)
- `note.status` (text)
…

Either way, this is the spec: bars-genre.vl.json. It is also in the starter, already wired to the base's Genres view.

4 spec

Read the spec, then make it yours.

The spec is plain Vega-Lite JSON. Read it top to bottom: the data is the base's notes; a bar mark; the genre down the side, a count along the bottom, color from the status. The filter drops books with no genre.

{
  "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
  "data": {
    "name": "base"
  },
  "mark": {
    "type": "bar",
    "tooltip": true,
    "cornerRadiusEnd": 3
  },
  "encoding": {
    "y": {
      "field": "note.genre",
      "type": "nominal",
      "sort": "-x",
      "title": "genre"
    },
    "x": {
      "aggregate": "count",
      "title": "Notes"
    },
    "color": {
      "field": "note.status",
      "type": "nominal",
      "title": "status"
    }
  },
  "transform": [
    {
      "filter": "isValid(datum[\"note\"][\"genre\"]) && datum[\"note\"][\"genre\"] !== ''"
    }
  ]
}

Where to edit it. Obsidian has no JSON editor of its own, so install one plugin once: the JSON Editor community plugin (source and tree views, desktop and mobile). Then hover the chart and click Edit spec ({ }, top right), or run Agate: Edit the spec of the last chart: the spec opens to the left of the chart, and every save redraws it. Settings → Agate → Editing specs links to the plugin and can show .json files in the file explorer.

5 note

Put it where you write.

The chart is a view of the base, so it shows up wherever a base can. Embed it in any note by name:

![[Books.base#Bookshelf with covers]]

Or point an agate block at the spec and the base, which leaves the base's own views alone:

```agate
spec: charts/bookshelf-covers.vl.json
base: Books.base
```

Add a book note and the bar grows; filter the base to this year and the chart follows.

The numbers above the chart are a spec too: Vega counts and sums over the same base, and Agate shows the result as note text instead of a chart. The starter's Numbers view uses reading-stats.vl.json; how it works is in the guide's big numbers section.