Your First Dotabase

In this walkthrough you will build a small Dotabase from nothing: create it, give it a property, add a few rows, connect two of them with an edge, and look at the result as a graph. It uses the dots CLI throughout and takes about ten minutes. Make sure dots auth whoami succeeds before you start.

1. Create The Dotabase

This walkthrough tracks a small reading list. Create it with a name, a slug, and a row-id prefix:

dots dotabases create --name "Reading list" --slug reading-list --prefix READ

The slug is how you address the Dotabase from the CLI from here on, and the prefix is what row ids are built from — the first row becomes READ-1, the next READ-2, and the counter never reuses a number after a delete.

2. Declare A Status Property

A new Dotabase has a deliberately small schema: a required title and a rich-text body, and nothing else. Rows may only carry properties the schema declares, so before you can record whether a book has been read, the Dotabase needs somewhere to put that. Save this as status-property.json:

[
  {
    "id": "status",
    "key": "status",
    "display_name": "Status",
    "type": "select",
    "config": {
      "options": [
        { "id": "read", "name": "Read", "color": "data" },
        { "id": "to-read", "name": "To read", "color": "ideas" }
      ]
    }
  }
]

Then append it to the schema:

dots dotabases schema add-property reading-list --file status-property.json

A select property is a closed roster: the two option ids above are the only values a row's status may take, and a value outside the roster is refused at write time rather than stored. Option ids are lowercase and hyphenated, which is why "To read" is identified as to-read.

3. Add A Few Rows

Each row is a book. --set fills a property; the title is the book's title:

dots rows create reading-list --title "Thinking, Fast and Slow" --set status=read
dots rows create reading-list --title "The Undoing Project" --set status=to-read

Had you skipped step 2, both of these would have failed rather than silently dropping the status — the write names a property the schema does not declare, and the platform refuses it and tells you which keys are legal.

4. List And Filter The Rows

List them to see the ids the prefix produced:

dots rows list reading-list --level scan

You should see READ-1 and READ-2. --level scan is the cheapest read the CLI offers: it keeps each row's identity — id, title, icon — and nothing else, which is exactly what you need in order to pick a row to open. Drop the flag and the listing lands one tier wider at summary, which adds the DIIICE classification, the edge count, and the closed-value properties such as the status you declared in step 2. --level full is the whole record, body included. Narrow the list by title substring:

dots rows list reading-list --title-contains Undoing

That match is case-sensitive, so Undoing finds the second book and undoing finds nothing. Title is a system slot present on every Dotabase, so this filter works whatever your schema looks like. Filters and tiers narrow different axes — one picks which rows come back, the other how much of each — so they compose freely.

5. Connect Two Rows

The two books are related — one is about the people behind the other. Draw a typed, directed edge between them. dots edges create takes the Dotabase, the source row, the target row, and the edge type:

dots edges create reading-list READ-2 READ-1 references

That records READ-2 references READ-1 in the knowledge graph. references is a built-in edge type whose inverse is referenced_by, so the relationship is traversable from either book without drawing a second edge.

6. Read A Row Back

dots rows get reading-list READ-1

The CLI prints the row as an agent envelope — its properties as frontmatter, its body beneath. This is the same envelope an AI agent sees.

7. See It As A Graph

Open the Dotabase in the web app and switch to the graph view. Your two books appear as nodes, joined by the edge you drew. Switch to the table or board view to see the same rows arranged differently — every view is a lens over the one set of rows.

What You Built

You created a Dotabase, declared a property to widen its schema, added rows carrying that property, filtered them, connected two into a graph, and read one back as an envelope. Structure in Dots is explicit at every one of those steps: a Dotabase holds what its schema declares, and the rest of the platform reads that declaration rather than inferring it. Import from Markdown loads existing notes into a Dotabase instead of typing rows one at a time. Connect Your Agent hands the same operations to an AI assistant over MCP.