stats
Dashy vault/Reference/stats
Reference/stats.md

stats: the numbers

Properties
code block
stats
keys
9 on the block, 23 on each card
checked on
Dashy 2.2.0

Number cards: one value per card, computed over a selection of notes.

Prefer to have your agent write it? Build a dashboard with an AI agent.

From the demo vault

stats
```stats
columns: 4
items:
  - { label: Days logged, source: Diary, agg: count, icon: 📔 }
  - { label: Average sleep, source: Diary, field: sleep_score, agg: avg, precision: 1, trend: 30d }
  - { label: Steps this week, source: Diary, field: steps, agg: sum, unit: steps, period: week }
  - { label: Best night, source: Diary, field: sleep_score, agg: max, trend: 90d }
  - { label: Longest streak, source: Diary, field: sleep_score, agg: streak, unit: days }
  - { label: Latest steps, source: Diary, field: steps, agg: latest, sub: most recent note }
  - { label: Great nights, source: Diary, where: "sleep_score >= 90", agg: count }
  - { label: Books read, source: Books, period: year, date_field: finished, agg: count, icon: 📚 }
```
renders as
Eight number cards: counts, an average, sums, a maximum, a streak, two with sparklines

A minimal block

The shortest config worth pasting. Change the folder and the property names to yours.

stats
```stats
columns: 3
source: Diary
items:
  - { label: Notes, source: 01-Areas, agg: count }
  - { label: Sleep, field: sleep_score, agg: avg, precision: 1, trend: 30d }
  - { label: Best streak, field: sleep_score, agg: streak }
  - { label: Gym this week, field: gym, agg: sum, period: week, compare: true, better: up }
```

Keys on the block

KeyWhat it doesTypeDefault
columns columns in the grid, 1 to 6. On a phone a block never shows more than two columns number 3
layout cards draws a grid of cards; inline draws the same numbers as one line of text, like 1001 notes · 188 journal entries · 14 open tasks, for a page header. Inline keeps icon, unit and the compare delta, but draws no trend, no sub and no group_by card and ignores columns, with one warning for each. An unrecognised value warns and falls back to cards text cards
items required the list of cards list none
sourcealso folder, from folder for every card that names none of its own; includes nested ones. A card's own source replaces it text none
tag tag for every card that names none of its own, with or without the hash. A card's own tag replaces it text none
where conditions every card must meet, written like a card's where. A card's own where does not replace it but narrows further: both must hold text or list none
period window for every card that sets none of its own, written like a card's period. A card's own period replaces it text or number or map none
date_field date property for every card that sets none of its own, written like a card's date_field. A card's own date_field replaces it text none
date_format date format for every card that sets none of its own, written like a card's date_format. A card's own date_format replaces it text none

Keys on each card

Each entry under items is one card.

KeyWhat it doesTypeDefault
label requiredalso title, name caption under the number, or after it with layout: inline text none
sourcealso folder, from folder; includes nested ones text none
tag tag, with or without the hash text none
where a condition like year = 2026, rating >= 4, tags contains books, or several that must all hold: joined with and (year = 2026 and rating >= 4) or written as a list ([year = 2026, "rating >= 4"]). The field name may be a dotted path into a nested property, like health.sleep > 70. date empty keeps the notes where a property is missing, blank or an empty list, and date not empty the notes where it holds a value, 0 and an unticked checkbox included. or is not supported; quote a value holding the word and or or. One unreadable condition drops the whole filter with a warning, and the numbers are drawn unfiltered text or list none
period narrow to a window: week, month, year (the current calendar one) or a rolling count of days like 30d, all ending today; note, the day, week, month, quarter or year the name of the note this block sits in stands for, like 2026-W40; a period written out the same way: 2026-10-01, 2026-W40, 2026-10, 2026-Q4 or 2026; or { from: 2026-09-01, to: 2026-09-30 }, both days included, from alone running to today. Notes without a date are left out first, then every agg, count included, runs on what remains. A week starts on the first day of the interface language, Dashy's own when one is picked in its settings, otherwise Obsidian's: Sunday in English, Monday in most European languages; a week named like 2026-W40 is the seven days its name stands for text or number or map none
date_field a date frontmatter property to read instead of the note name: 2026-03-02 or 2026-03-02T10:30, or in date_format, or a dotted path into a nested property like meta.date. Feeds period's window, the streak, current_streak, latest and trend readings and the date origin shows; has no effect on count, sum, avg, min or max without period or origin text none
date_format a date format for note names and date_field values not written as YYYY-MM-DD, in moment notation: DD.MM.YYYY, MM/DD/YYYY, YYYYMMDD. Tried after YYYY-MM-DD and before the day format of the Daily notes or Periodic Notes settings, which is read without this key. A name or a value only has to start with the date (05.10.2026 Monday and 05.10.2026 14:30 count); the match is strict, so 5.10.2026 and 31.02.2026 are no date under DD.MM.YYYY. Needs a year, a month and a day, and warns when no selected note fits it. Steers the same readings date_field does. Month and weekday names (MMMM, dddd) are read in Obsidian's language, or in the Plugin language setting when one is picked text none
compare true shows the delta against the same stretch of the previous period, to date, and the previous value after it, formatted like the card: ▲ +1 (was 3). This week compares against the same weekdays last week, not the whole of last week. A fixed period already over compares against the whole period before it, June against all of May; a from/to against as many days right before from. usual shows the delta against the usual level instead: the average of the same field over every note in the card's selection dated before the window starts, the window itself left out. usual works with agg: avg only and warns with any other aggregate; with no note before the window the card says there is no history yet instead of a delta, as a tooltip on the number under layout: inline. Only with period set, and not with agg: streak or current_streak true or false or text none
better up colours a rise green and a fall red; down reverses that for a number where less is better. No change stays neutral either way. Only with compare: true or compare: usual text none
fieldalso property, prop numeric frontmatter property, or a checkbox (ticked counts as 1, unticked as 0), dotted for a nested one like health.sleep; required for everything but count, streak and current_streak. A field missing from the whole selection, or holding text rather than a number, shows a dash and a warning naming it; count text instead with where: "field contains ..." and agg: count. A duration string like 5h 58min, 1h30m, 45m, 90 min, 7:30 or ISO 8601 PT1H45M counts as minutes (ISO years and months, like P1M, are not durations; PT1M is a minute), and sum, avg, min, max or latest over a field of durations shows 5h 58m. When every value of the field across the selected notes carries seconds, like 2:16:32 or 2h 16m 32s, the card shows a clock to the second instead: 2:16:32, 0:18:51, and so does a compare delta. H:MM is always hours and minutes, never a time of day or minutes and seconds: a 5 km time written 18:51 reads as 18 hours, so write race times as 0:18:51. A field mixing durations and plain numbers counts both as minutes, shows a plain number and warns naming a note of each kind. Also takes a list, like [run_min, bike_min, swim_min], for one number over several properties: each note's value is the sum of the listed properties it holds, a note holding none of them is left out rather than counted as 0, and agg then works on those per-note totals, so avg is the average of the notes' totals and max the biggest one. A list of one is that one field. For streak and current_streak a day is filled when any listed property is, and at_least/at_most compare the day's total. Durations and plain numbers add up as minutes, under the same mixing rule as one field. Each listed property missing from the selection, or holding only text, warns by name, and the others still count; an empty list or an item that is not a property name is an error, and a name listed twice counts once and warns. This differs from a list in the field of a chart series entry or of a heatmap, which pools every single value, so a chart's avg or a heatmap's per_day: avg averages properties rather than notes text or list none
aggalso aggregate count sum avg min max latest streak current_streak text count
at_least with agg: streak or current_streak only: a day counts only once its notes' field values, summed for that day, reach this, like at_least: 5000 steps; combine with at_most for a range. Needs field; ignored on any other aggregate. Takes a duration like 7h or 7:30 too, read as minutes; a plain number against a field of durations means minutes number or text none
at_most with agg: streak or current_streak only: a day counts only while its notes' field values, summed for that day, stay at or under this, like at_most: 5 cigarettes; combine with at_least for a range. Needs field; ignored on any other aggregate. Takes a duration like 7h or 7:30 too, read as minutes; a plain number against a field of durations means minutes number or text none
days with agg: streak or current_streak only: weekdays makes Saturday and Sunday transparent, so they neither break the run nor add to it, whatever they hold; all, the default, counts every day. Ignored on any other aggregate text all
skip_field with agg: streak or current_streak only: a property marking a day special, like vacation: true or sick: flu; a day is special once any note landing on it sets the property to anything other than false, a blank string, 0 or absent. A special day neither breaks the run nor adds to it, whatever field holds, the same way days: weekdays treats a weekend, and the two combine. Ignored on any other aggregate text none
unit a suffix after the number: km, %, d. Ignored, with a warning, on a value shown as a duration, which carries its own units. The count nouns day, week, month, year, night and time agree with the number: 1 day, 2 days; any other unit stays as written. text none
precision decimal places, 0 to 6; by default a whole number stays whole and a fraction gets one decimal; no effect on a value shown as a duration number none
trend sketch the last N days ending today, or on the last day of a period window already over: 30d. Needs field. Its own trailing window, independent of period text or number none
iconalso emoji emoji text none
sub small caption under the title text none
origin with agg: latest, min or max only: say where the value came from, under the label. note shows the name of the note it was taken from, as a link; date shows that note's date in the interface language, read like the rest of the card (date_field, date_format, the note name). When several notes share the smallest or largest value, the newest of them is named. After sub when both are set. A card key only, not inherited from the block root; not shown with layout: inline text none
group_by a property whose values each get a row: the card ranks them, the value's name and its number, best first, instead of showing one number. agg and field work per value, count by default: { label: Games by platform, source: Games, group_by: platform } counts the games on each platform, { label: Best rating by genre, source: Games, group_by: genre, field: rating, agg: max } shows each genre's best rating. Ranked from the largest number down, except agg: min, ranked from the smallest up, the best time first; a tie goes to the value's name in alphabetical order. A note whose property is a list, like genres: [rpg, indie], counts in each of its values, and a line under the card then says the rows can add up to more than the number of notes. Values group regardless of case and show in the spelling most notes use; a link like [[Switch]] or [[Consoles/Switch|my Switch]] shows as the note's name, Switch, and groups with the plain text Switch; numbers and checkboxes group by their text. The notes where the property is missing or empty form one muted no value row, always last, outside the ranking and limit; leave them out with where: "platform not empty". precision, unit and the duration format apply to every row. compare, better, trend and origin describe one number and are ignored on such a card, with a warning; it is not drawn with layout: inline. A property no selected note has warns: every note would land under no value. A card key only, not inherited from the block root text none
limit with group_by only: how many rows to show, the best ones; the rest fold into one line, +3 more values. A whole number of 1 or more; anything else warns and shows 10. The no value row does not count towards it number 10

How it behaves

  • streak counts the longest run of consecutive days and latest takes the value from the newest note, a tie on the same date broken by path. Both resolve a note's date the same way period does, below, and two or more notes landing on the same day count as one day. With a field: set, streak is a field aggregate like sum or avg: nothing to count shows a dash, even over an empty selection. Without a field: it counts every selected note's own date instead, and reads a plain 0 when there is nothing, the same as count. streak is the best run on record: label the card "Best streak" or "Longest streak". current_streak is the run going on now, counted back from today by the same rules: label the card "Current streak" or "Days in a row". Today never breaks it: a day not filled yet leaves the run counted up to yesterday, and only a gap on yesterday or earlier resets it to 0. It counts within the selection after period, where, tag and source, so period: month stops it at the first of the month.
  • count over nothing reads a plain 0, the number of notes found; every other aggregate, and streak or current_streak with a field set, shows a dash instead: "no data" and "zero" are different answers.
  • trend sketches the days of a trailing window ending today, scaled between the smallest and largest value in that window rather than from zero. A day without a note is left out, not drawn as a zero, and two or more notes on the same day are summed into that one day's bar.
  • period narrows to a calendar week, month, year or a rolling Nd, ending today, or to a fixed window, below. A note's date is its name, as long as it starts with YYYY-MM-DD (2026-03-02 Monday counts, 2026-03-021 does not) or with a date in date_format or in the Daily notes day format, unless date_field names a property instead; a note with no date under either rule is left out before counting.
  • compare: true keeps the previous period's number in sight for a review table: { label: Gym days, field: gym, agg: sum, period: week, compare: true, better: up } reads 4 with ▲ +1 (was 3) beside it, the previous value in the card's own format and unit; for a window that is still running it is the same days of the previous period to date, and the whole period once it is over. On a narrow card (was 3) wraps to its own line whole. compare needs a note in both windows; when either the current or the previous stretch has none at all, the card shows its number alone with no delta and no previous value. streak and current_streak have no value of their own to compare and refuse compare outright, the way trend refuses count.
  • Durations written in ISO 8601, as some apps and exports store them, count as minutes like any other: focus: PT1H45M is 105 minutes, so { label: Focus, field: focus, agg: sum, period: week } over PT1H45M, PT45M and PT6H58M reads 9h 28m. Any non-empty subset of PnWnDTnHnMnS in that order works, in either case: PT90S, PT0.5H, P1DT2H, P2W. Years and months (P1Y, P1M) are not durations, their length varies, and such a value reads as text; PT1M is a minute.
  • compare: usual answers "is this week normal for me": { label: Sleep, field: sleep_score, agg: avg, period: week, compare: usual, better: up } reads 82 with ▼ −3 beside it when every earlier note averages 85, and the tooltip says vs usual: 85. In a weekly review note named 2026-W40, period: note at the block root does the same for that week: period: note with items: [{ label: Sleep, field: sleep_score, agg: avg, compare: usual, better: up }]. The usual level is the average over every note in the card's selection dated before the window, however old, so the week is never measured against an average it is part of; it is formatted like the card, 6h 12m for durations. It needs agg: avg and a period, written on the card or at the block root.
  • at_least/at_most turn streak into a threshold: a day counts only when its notes' field values, summed for that day, satisfy the bound, at_least: 5000 on steps for example. days: weekdays makes Saturday and Sunday transparent for streak and current_streak: they neither break the run nor extend it, whatever they hold, so a Friday followed by a Monday is a run of two. skip_field does the same for a day any note marks special, vacation: true or sick: flu for example, and combines with days: weekdays. All three keys apply to agg: streak and agg: current_streak only and are ignored on every other aggregate.
  • source, tag, where, period, date_field and date_format written at the block root, next to items:, apply to every card, so a folder shared by the whole block is written once. A card's own source, tag, period, date_field or date_format replaces the root's for that card; where is the exception: the root's conditions and the card's own both hold. A root folder that does not exist, a root where or period that cannot be read, a blank root source or tag, a root date_field that no note selected under period has a date in, or a root date_format that none of the notes its cards select fits is reported once for the block, not once per card. A card's own source: or tag: left empty still replaces the root's, so the card reads the whole vault or drops the tag filter, and it warns: to inherit the root's value, remove the key. Without items: the block is a single card and these keys are simply its own.
  • layout: inline draws every card as one item of a single line, its number first and its label after, joined by a middle dot: items: [{ label: notes, agg: count }, { label: journal entries, source: Journal, agg: count }] with layout: inline reads 1001 notes · 188 journal entries, so a lowercase label reads best there. A compare delta follows the label, coloured the way it is on a card. A narrow pane wraps the line between items, never inside one. A card whose number cannot be computed shows a dash in its place and the rest of the line still draws.
  • Daily notes named another way, like 05.10.2026, are read in the day format set in the Daily notes or Periodic Notes settings, with no key at all. Without that setting, name the format: date_format: DD.MM.YYYY. A time after the date is fine (2026-10-05-14:30), but an order that could be read two ways, like 05-10-2026, is never guessed: without a format it is not a date.
  • A weekly review: in a note named 2026-W40, period: note at the block root counts that week and no other, however late the note is opened: period: note with items: [{ label: Gym, field: gym, agg: sum, compare: true }, { label: Sleep, field: sleep_score, agg: avg }]. A period written out works anywhere: period: 2026-Q4, or period: { from: 2026-06-01, to: 2026-08-31 } for a season. The name is read in the formats set in Periodic Notes for each period (one switched on there with no format saved, in the plugin's default, so a week is the locale week gggg-[W]ww), the day falling back to Daily notes, then as ISO: YYYY-MM-DD, GGGG-[W]WW, YYYY-MM, YYYY-[Q]Q, YYYY, the day first, so 2026 never takes 2026-10. The note's name may go on after the day, week, month or quarter, past a space, _ or - and not straight into a digit (so a time after the day, 2026-10-05 14:30, is not read here): 2026-W41 Weekly is that week, 2026-10 Monthly Review that month; a year takes nothing after it, so 2026 goals is no period, and a period written in the block, period: 2026-W41, takes nothing after it either. In a weekly format ww with gggg is the week by the rules of Obsidian's language, WW with GGGG the ISO week. YYYY is the calendar year: paired with ww or WW it names a week across New Year with the wrong year, and a block in such a week warns and suggests gggg or GGGG. A note named otherwise is an error that lists those formats; nothing is guessed. In a template, a note in the template folder of the core Templates plugin or of Templater, a name that is no period is no error: the block draws no numbers but a line saying the note is a template, under any other problem the config has, and a note made from it and named for a period counts that period. A window already over compares against the whole period before it, June against all of May however long each is; a from/to against as many days right before from; one still running against the same days of the period before, as period: week does. current_streak counts back from the window's last day, and trend ends there. A window already over does not forgive that day the way a running one forgives today: a closed week with its last day unticked reads 0. A window that has not started yet, a note on next week, draws no cards, only the day it starts. period: 2026 is the year 2026; write 2026d for a count of days.
  • One number over several properties: { label: Workout minutes, field: [run_min, bike_min, swim_min], agg: sum, period: week } adds up the three in each note, a note holding only bike_min counting that alone and a note with none of them left out; agg: avg on the same list averages those per-note totals. Without a label the card is named run_min + bike_min + swim_min.
  • Records with the race name: { label: Best 10k, source: Races, field: time, agg: min, origin: note } reads 0:48:05 with the note it came from, 2025-09-14 Autumn 10k, linked under the label; { label: Ferritin, source: Labs, field: ferritin, agg: latest, origin: date } shows the date of the last analysis instead, like Sep 22, 2026. origin works with latest, min and max only and describes the value in the card's own window, never the previous one compare reads. Two races with the same best time name the newer one. With origin: date, a note with no readable date shows no caption and a warning naming it. A hand-written sub stays and comes first: sub: personal best with origin: note reads personal best · 2025-09-14 Autumn 10k.
  • Counting notes by a property: { label: Games by platform, source: Games, group_by: platform, limit: 5 } draws one card with a row per platform, Switch 12, PC 9, PS5 4, the largest first, and +2 more values under the fifth. agg and field work per value: { label: Hours by platform, source: Games, group_by: platform, field: hours, agg: sum } adds up each platform's hours, and { label: Best time per course, source: Races, group_by: course, field: time, agg: min } shows each course's best time, smallest first. The selection, on the card or at the block root (source, tag, where, period), narrows the notes before they are grouped. This is a number per value; a list of the notes themselves is Obsidian Bases.