Bases and saved views

A base is a database-style view over your knowledge base. Each base is a saved view: a named DQL query plus presentation settings, stored as JSON under .kiwi/views/. Open Bases in the web UI to browse the results, or run the same view from the API or MCP. Use a base when you want a reusable slice of your pages, such as all open incidents, every paper tagged llm, or vendors that have an office location.

How it works

Pages carry frontmatter

Every field you want to query lives in YAML frontmatter, for example status, owner, or due.

A view stores a DQL query

The view’s query selects and shapes rows. Filtering and sorting belong in the query (WHERE, SORT).

Executing the view runs the query

GET /api/kiwi/views/{name}/execute runs the query against the frontmatter index, then evaluates any computed formula columns.

The web UI renders the rows

Bases shows the result in the view’s default layout. You can switch layouts and quick-search the loaded rows without editing the view.

Executing a view requires the default SQLite search engine. With [search] engine = "grep", the execute endpoint returns 503.

File format

Each view is one JSON file named after the view.

.kiwi

views

open-incidents.json

reading-list.json

.kiwi/views/open-incidents.json

{
  "name": "open-incidents",
  "query": "TABLE title, severity, owner, minutes_down FROM \"incidents\" WHERE status != \"resolved\" SORT severity ASC",
  "layout": "table",
  "columns": [
    { "property": "minutes_down", "label": "Downtime", "summary": "sum" },
    { "property": "hours_down", "label": "Hours", "formula": "round(minutes_down / 60, 1)" }
  ]
}

Field	Purpose
`name`	Identifier. It always matches the filename; on save, the name in the URL wins.
`query`	DQL query run by the Dataview engine. It must start with a query type such as `TABLE` or `LIST`.
`layout`	Default layout in the web UI: `table`, `cards`, `list`, or `map`.
`columns`	Optional column specs: `property`, `label`, `formula` (computed value), and `summary` (`sum`, `avg`, `count`, `min`, `max`).
`filters`	Optional structured filters (`field`, `operator`, `value`). Stored with the view but not applied by the execute endpoint, so put filtering in the query.
`sort`	Optional sort keys (`field`, `order`). Stored only; use `SORT` in the query.
`group_by`	Optional grouping field. Stored only.

View names must start with a letter or digit and may contain letters, digits, spaces, hyphens, and underscores.

Computed columns

A column with a formula is evaluated for each row after the query runs, and the result is written into that column’s property. Formulas support:

Field references, numbers, and quoted strings
Arithmetic with +, -, *, and /
length(x), round(x, digits), and if(field, then, else), where the condition is true when the field is set and not empty

Layouts in the web UI

Layout	Best for	Notes
Table	Comparing fields side by side	Shows column `summary` values in the footer.
Cards	Visual collections	Uses a `cover` or `image` frontmatter field as the card image.
List	Compact scanning	Title plus key fields.
Map	Places	Plots rows that have `latitude` and `longitude`, `lat` and `lng`, or a `location` string such as `"52.37, 4.89"`.

Hide the Bases toolbar button with bases = false under [ui.features].

Create and run a view

REST
MCP
Web UI

Terminal

curl -X PUT 'http://localhost:3333/api/kiwi/views/open-incidents' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "TABLE title, severity, owner FROM \"incidents\" WHERE status != \"resolved\"",
    "layout": "table"
  }'

curl 'http://localhost:3333/api/kiwi/views/open-incidents/execute?limit=50'

Call kiwi_views_save to create or update the view, then kiwi_views_execute to run it. kiwi_views_list, kiwi_views_get, and kiwi_views_delete cover the rest.

Click Bases in the toolbar, then New view. Enter a name and a DQL query such as TABLE title, status FROM "incidents", pick a default layout, and click Save.

Saved views are configuration under .kiwi/, not pages. Saving one writes the JSON file directly; it does not create a git commit or appear in search.

Saved views versus computed views

Saved views live in .kiwi/views/ and render in the web UI. Computed views are markdown pages with kiwi-view: true and a kiwi-query in frontmatter. KiwiFS writes the query result into the page body between  and  markers, so any tool that reads the file sees the result. Regenerate one with POST /api/kiwi/view/refresh or the kiwi_view_refresh MCP tool. See DQL for details.

Views REST API

List, save, delete, and execute views.

DQL

The query language behind every view.

Metadata API

Query frontmatter directly.

Web UI

Toolbar views, including Bases.

Getting Started

Core Concepts

Widgets

Guides

Data Import

Data Export

Deployment

How it works

File format

Computed columns

Layouts in the web UI

Create and run a view

Saved views versus computed views

Views REST API

DQL

Metadata API

Web UI

​How it works

​File format

​Computed columns

​Layouts in the web UI

​Create and run a view

​Saved views versus computed views

​Related

Views REST API

DQL

Metadata API

Web UI

How it works

File format

Computed columns

Layouts in the web UI

Create and run a view

Saved views versus computed views

Related