Database

Every organization can have its own database: a place for structured data such as customer lists, orders, inventories, logs or anything else worth keeping in tables. Agents read and write it with tools, and you work with it through a chat on the Database page.

The database is private to your organization. Only its members can see the data, only editors and admins can change it, and the activity log shows who did what.

You don't need any database experience to use it. If you'd like to understand the ideas behind it, start with Relational database basics.

Create your first table

Creating tables takes the organization Admin role.

1. Open Database in the sidebar.

2. Describe what you want to keep track of in plain words, for example:

   We sell products to customers. Keep track of each customer and their orders.

3. The assistant proposes the tables and their columns. Check that they cover what you need, ask for changes, and approve them.

4. Keep going in the same chat: add rows, change them, or ask questions about the data.

To let an agent use the tables too, give it database access.

The Database page

Open Database in the sidebar. The page has two halves:

• The chat on the left. The assistant proposes tables, creates them after you agree, and adds, changes and looks up rows for you. Every change to the database goes through this chat.
• The schema on the right: the tables with their columns, types, defaults, descriptions and indexes. A table's name opens its rows.

Two more pages are listed under the Database title next to the chats:

• Data: the rows of a table, with search, sorting and paging.
• Activity: the log of every change and query run against the database, by whom, with what outcome.

Schema changes (creating, altering or dropping tables and indexes) ask for your approval in the chat before they run. Deleting or updating every row of a table, and dropping a table, are confirmed with you first.

Who can do what

Agents and the database

A custom agent gets database tools according to its Database access level, which an organization admin sets in the agent's settings under Model & Capabilities. The levels build on each other: every level includes everything the levels below it allow.

No access

The agent has no database tools at all. It can neither see that the database exists nor read anything from it. This is the default for a new agent.

Read

The agent can look at the data but never change it:

• List Tables and Describe Table: see which tables exist, their columns, descriptions and indexes.
• Query Rows: look up rows with filters, sorting and paging.
• Run SQL Query: run a read-only SQL query, for example to join tables or compute totals.

Choose this level for agents that answer questions, write reports or look things up for other tasks.

Read and write

Everything in Read, plus changing the data in existing tables:

• Insert Rows: add new rows.
• Update Rows: change existing rows.
• Delete Rows: remove rows.

The agent cannot create, change or delete tables, so the structure of your data stays as you designed it. Choose this level for agents that record things, such as orders, tickets or logs, or that keep data up to date. Deleting and updating rows cannot be undone, so consider making those tools ask for approval (see below).

Full

Everything in Read and write, plus changing the structure of the database:

• Create Table and Alter Table: add tables, or add, change and remove columns.
• Drop Table: delete a table with all its rows.
• Create Index and Drop Index: add and remove indexes.

These tools ask for approval by default, because a dropped table or column takes its data with it. Reserve this level for agents that build and maintain the database itself.

Tools and approvals within a level

Every chat with the agent, whoever starts it, and every scheduled run gets exactly the agent's level, even when the person chatting has a higher or lower role. Within the level, editors choose which of the tools the agent actually has and which ask for approval before running. An approval pauses the chat and shows the exact change; a scheduled run stops at the request and continues once someone opens the chat and approves it.

Only organization admins change the level. Changing it replaces the agent's database tools with the new level's tools and keeps the approval settings of the tools that stay.

In the general organization chat, the tools follow your own role (the table above).

Apps and the database

Your apps can use the database too: an editor allows an app to read, or to read and write, your tables, and from then on the app's functions work with the same data your agents and members see. An app never changes tables or columns, and every statement it runs shows up in the activity log under the app's name.

Limits and billing

• Database tool calls are priced like integration tool calls. Statements from apps are not charged.
• Each plan includes a storage quota (100 MB on Pay as you go, 1 GB on Pro). Above it the database only takes reads and deletes until space is freed or the plan is changed.
• A lookup returns at most 200 rows per call; agents page through larger results. Every operation is stopped after 10 seconds.
• The activity log is kept for 90 days.