Databases
Databases — Technical Reference
A technical look at how Databases store data, synchronize in real time, validates column types, and executes agent tasks.
This page describes how Databases behave beneath the interface, in technical terms, for developers and technically-inclined users. It assumes familiarity with relational databases, JSON, and client–server APIs, and it focuses on observable behavior and data contracts rather than implementation details.
Architecture model
Databases keep two concerns separate:
- Structure (metadata) — spaces, databases, column definitions, views, and connectors.
- Record data — the rows stored in each database.
Record data lives in a relational database and is isolated per workspace: every query is scoped to the owning workspace, and records from different accounts are never co-mingled.
Clients use two channels:
| Channel | Used for |
|---|---|
| REST API | Structure and metadata operations (spaces, databases, columns, views, connectors), AI queries, and exports |
| WebSocket | Record-level operations (select, insert, update, delete) and live updates broadcast to other connected clients |
Entities & relationships
| Entity | Description |
|---|---|
| Space | A namespace that groups related databases and maps to an isolated data container. |
| Database | A collection of records governed by a typed column schema. |
| Column | A typed field defined by a friendly type, an underlying storage type, and constraints. |
| Record | A row of column values, plus a rich-text content body and an icon. |
| View | A saved configuration (type + filters, sort, grouping, visible columns) over a database. |
| Connector | An external data source bound to a database that ingests records automatically. |
Storage & real-time synchronization
- Structural changes (databases, columns, views, connectors) are performed over the REST API. The client applies optimistic updates and rolls back if a request fails.
- Record operations run over a persistent WebSocket connection. Records load in batches (pagination); later batches append to earlier ones.
- When any client changes a record, the change is broadcast to other clients connected to the same database, which update live.
- Changes made programmatically — by AI agents, automations, or connectors — emit the same change notifications, so open clients refresh automatically.
Real-time page editing
Record page content uses a dedicated collaborative-editing channel, separate from the record-operations connection above:
- While a record page is open, all connected editors (users, edit-permission guests, and agents) share a live document. Edits merge with conflict-free semantics — concurrent changes from multiple editors combine deterministically, character by character, with no locking and no lost updates.
- The stored format remains markdown: the live document is persisted back to the record within seconds of edits stopping, and on the last editor disconnecting. Reads through agents reflect the live document, not just the last persisted value.
- Presence (named cursors and selections) is part of the same channel.
- If a client disconnects mid-edit, it rejoins by re-syncing to the current shared document; the shared version is authoritative.
Column type system
Every column has a friendly type (the user-facing type) that maps to an underlying storage type plus validation rules. Values are validated on write and rejected if they don't conform.
| Category | Types | Storage |
|---|---|---|
| Scalar | text, number, date, checkbox, email, url, phone, currency, rating, progress, duration, uuid | Storage primitives with constraints (ranges, formats) |
| Choice | status, select, multi_select | Validated against a defined option set |
| Composite | file, person, relation, multi_select | JSON-encoded values |
Composite values are stored as JSON. These shapes are the data contract the REST API and agent tools read and write:
| Type | Value shape |
|---|---|
file | { "url", "name", "size", "type" } |
person | array of { "type", ... } entries |
relation | { "id", "title", "icon", ... } |
multi_select | [ "Option A", "Option C" ] |
Choice values must match one of the column's configured options; numeric types (rating, progress, duration) enforce their ranges.
Views & the query model
A view stores a configuration object: its type plus filters, sort order, grouping, visible columns, and type-specific settings (for example, the grouping column for Kanban or the date column for Calendar).
- The configuration is applied at query time — filtering and sorting happen when records are fetched.
- Filter operators cover equality, comparison, substring, membership, emptiness, and boolean checks, with explicit NULL handling for negative operators (for example, "is not" and "is none of" include NULL values).
- For public and guest views, the view's embedded filters and hidden columns are enforced server-side and cannot be bypassed by the client. Viewer-supplied filters are layered on top for that session only.
Connectors
Connectors use a pull-based (polling) synchronization model rather than push delivery:
- New entries are fetched on a fixed interval (currently every 30 minutes). If a component is briefly unavailable, the next cycle catches up, so no entries are lost.
- Each cycle processes only entries created since the last successful sync, and deduplicates by the source's unique identifier.
- Columns a connector needs are created idempotently during setup and on ingest.
Agent Tasks
An agent task binds an agent + instruction + execution mode to a single record.
Execution states:
Modes: immediate, scheduled (a timestamp), or event-driven (a status/select column on the record reaching a target value, whether set by a person or an agent).
- Chains — an agent may update another record whose event trigger starts the next agent, forming multi-agent pipelines without an explicit workflow graph.
- Self-loop protection — a record already
pending,queued, orrunningcannot start a new task. - Concurrency & timeout — per-table caps on simultaneously running tasks (excess tasks wait for a free slot) and on execution time (then
timeout). - Each run produces an execution log: the record context supplied, the agent's reasoning, and its tool calls.
Programmatic access
Agents and automations operate on a database through a tool interface: select, insert, update, delete, structure introspection, and natural-language query.
- Each tool is generated against the database's column schema and includes format hints, so the agent supplies values in the correct shape — option lists for choice columns, currency codes, rating ranges, and the JSON shapes above for composite columns.
- Record-changing tools emit the same live-update notifications as edits made in the interface.
Limits & guarantees
- Record reads are paginated; large databases stream in batches.
- Composite values are JSON — clients must serialize and deserialize accordingly.
What's next
- Projects — the next section: give your agents documents and files to work from.
- Connect a database to an agent — the agent-side setup for the tools described here.