Database AI — Technical Reference
This page describes how Database AI behaves 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
Database AI keeps 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.
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 from the source on a fixed interval (currently every 30 minutes).
- Polling is chosen for resilience — if a component is briefly unavailable, the next cycle catches up and no entries are lost.
- Deduplication uses the source's unique identifier, so overlapping windows never create duplicate records.
- Each cycle processes only entries created since the last successful sync.
- Columns required by a connector are created idempotently during setup and on ingest, keeping the schema consistent.
Agent Tasks
An agent task binds an agent + instruction + execution mode to a single record.
Execution states:
Execution modes:
| Mode | Behavior |
|---|---|
| Immediate | Runs as soon as it is dispatched |
| Scheduled | Runs at a chosen timestamp |
| Event-driven | Runs when a chosen status/select column reaches a target value |
- Triggers — an event-driven task fires when its watched column changes to the configured value, whether that change came from a person or another agent.
- Chains — an agent may update another record, whose own event trigger then starts the next agent, forming multi-agent pipelines without an explicit workflow graph.
- Self-loop protection — a record already in
pending,queued, orrunningcannot start a new task, so an agent cannot re-trigger itself. - Concurrency & timeout — each table has a maximum number of simultaneously running tasks (excess remain
pending) and a maximum execution time, after which a task is markedtimeout. - Each run produces an execution log capturing 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.
- Public views are read-only; guest access is permissioned (view or edit) and confirmed by email verification.
- Org-shared data stays in the owner's workspace; collaborators operate on it in place, with no copies made.
What's next
- AI Features — the agent-facing tools and natural-language query in practice
- Agent Tasks — the user-facing guide to assigning agents to records
- Automations — coordinate database actions across multiple steps