# Records

Records are structured data stored on a page. Use them for anything you track, such as customers, decisions, hires, or incidents, so that people and agents can read them as data.

## Tables and logs

A page holds one of two kinds of records:

| Kind | How it works | Use it for |
|---|---|---|
| Table | Each row has a unique key. Writing a row with an existing key replaces that row. | Things that change, such as customers, open roles, or decisions. |
| Log | Each entry is added with a timestamp. Entries are never replaced. | Things that happen, such as deploys, calls, or daily metrics. |

A page is a table if its metadata sets a `key`. A page with records and no `key` is a log.

## Create a table

Ask your agent, for example: "Make a table at crm:customers, keyed by id, with name, stage, and owner."

To create one with the CLI, write the page and then set its key:

```
known acme wiki write crm:customers --title "Customers" --text "Every customer, keyed by id."
known acme wiki meta crm:customers --text '{"key": "id"}'
```

To make sure every row has the fields you expect, add a [schema](https://known.info/docs/schemas).

## Write records

Use `wiki set` to write a row to a table or add an entry to a log:

```
known acme wiki set crm:customers --text '{"id": "acme", "name": "Acme", "stage": "pilot", "owner": "sam"}'
known acme wiki set ops:deploys --text '{"service": "api", "version": "1.42.0"}'
```

On a table, `wiki set` replaces the whole row. Fields you leave out are removed. To update one field, read the row, change the field, and write the full row back.

To make sure nobody changed the row since you read it, pass the row's version with `--if-version <n>`. The version is in the row's `_v` field. If the row has changed, the write fails.

On a log, `wiki set` adds an entry with the current time. To record something that happened earlier, add `--ts <time>`.

To delete a record, use `wiki del`:

```
known acme wiki del crm:customers/acme
```

## Read records

```
known acme wiki records crm:customers
known acme wiki get crm:customers/acme
known acme wiki records ops:deploys --reverse --limit 20
known acme wiki records ops:deploys --since 2026-10-01T00:00:00Z
```

| Command | Returns |
|---|---|
| `wiki records` | All records. Table rows are sorted by key; log entries by time, oldest first. |
| `wiki get` | One record, by its key or, on a log, its `_id`. |
| `--reverse` | Newest first on a log, highest key first on a table. |
| `--since`, `--until` | Log entries in a time range. |

Results are returned in pages of up to 1,000 records. To get the next page, pass the `--cursor` value from the previous result.

## System fields

Known adds these fields to every record:

| Field | Description |
|---|---|
| `_ts` | When the record was written. |
| `_actor` | Who wrote it. |
| `_v` | On a table, the row's version number. |
| `_id` | The record's ID. |

Your own field names can't start with `_`.

## Records in the browser

A page with records opens on its **Data** view, which shows the records in a grid. You can sort and filter the grid. Your sort and filter settings are saved in your browser.

If a table row has a `content` field with text, the row opens as its own page, with `content` shown as Markdown. Search and links use a row's `title` field as its name, or its `name` field if it has no title.

You can't edit records in the browser. Use an agent or the CLI. The grid updates as soon as a record changes.

## Row history

Tables keep every version of every row, including deletions:

```
known acme wiki history crm:customers/acme
known acme wiki diff crm:customers/acme --version 3
```

To read a whole table as it was at a point in time, use `wiki records --at <time>`. Log entries have no versions, because they can't be changed.

## Limits

- A record is a JSON object of up to 16,384 characters.
- A page can hold any number of records.
- Writing records doesn't create page revisions.

## FAQ

### What can agents do with records?

Agents can read, write, and delete table rows. Only people can delete log entries, remove a page that holds records, change a table's key, or lower a retention limit.

### Can I search log entries?

No. Search includes pages and table rows only. To find log entries, use `wiki records` with `--since` and `--until`.