Databases
Query, edit, and structure your Softr databases through an AI assistant.
These tools cover Softr Databases — reading and writing records, and building the tables and fields that hold them. They work on Softr’s own database engine. To reach data in external data sources, see Integrations.
Databases belong to a workspace. database_create needs a workspace ID. database_list returns the databases your token reaches, most recently updated first, and can narrow them to one workspace or to names that contain some text. database_search finds a database by keywords in its name or description. See Finding a database.
How the assistant works with your data
A few things shape the results you get.
It reads the field reference first. database_get_field_reference returns the authoritative reference for field types, their options, and the operators available for filtering. It is the same for every table, not the schema of one — database_get_table gives that. A well-behaved assistant calls it before creating tables or fields and before building a filter, rather than guessing.
Field keys are IDs, not column names. A record comes back keyed by field ID, not by the label you see in the table. database_list_fields maps between the two, which is why the assistant may look up a table’s fields before it can talk about a record in your terms.
Some fields cannot be written to. Formula, lookup, rollup, and count fields are computed from other data. Created time, updated time, created by, updated by, autonumber, and record ID are managed by Softr. The assistant can read all of them but cannot set them, and cannot change a field’s type after it is created.
Deleting is possible, and permanent. Records, fields, tables, and whole databases can all be removed through the assistant. There is no undo and nothing to restore from afterwards, so the assistant is expected to confirm with you before it deletes anything. See Deleting data.
Field reference
| Tool | What it does |
|---|---|
database_get_field_reference | Returns the full reference of field types, their options, and the available filter operators |
Databases
| Tool | What it does |
|---|---|
database_list | Lists the databases you can access, with table counts. Filters by workspace and by name, and can stop after a number of results |
database_search | Finds databases whose name or description matches some keywords, best match first |
database_get | Gets one database’s details |
database_create | Creates a database in a workspace |
database_update | Renames a database or changes its description |
database_delete | Deletes a database with every table and record in it |
Finding a database
An account can hold dozens of databases, so the assistant narrows the list instead of reading all of it. database_list takes three optional filters:
| Filter | What it does |
|---|---|
workspaceId | Lists only the databases of this workspace. A workspace you are not a member of returns an error, not an empty list. |
name | Keeps the databases whose name contains this text. Case does not matter: bug finds “Bug Tracker”. |
limit | Returns at most this many databases, from 1 to 200. hasMore in the answer says whether more matched. |
By default each database comes back with its ID, its name and its number of tables. The workspace ID is added when the list covers more than one workspace. Ask for details to also get the description, the dates, and the time zone and locale settings.
database_search is for when the assistant knows what a database is about but not its exact name. It matches keywords in the name and the description, ignores case, accents and plurals, and lists the best matches first.
Tables and fields
| Tool | What it does |
|---|---|
database_list_tables | Lists a database’s tables, with record counts |
database_get_table | Gets a table’s full schema, including every field definition |
database_create_table | Creates a table with an initial set of fields |
database_update_table | Renames a table or changes its description |
database_delete_table | Deletes a table with its fields, views, and records. Cannot delete a database’s only table |
database_list_fields | Lists a table’s fields with their types and configuration |
database_create_field | Adds a field. Supports text, number, select, date, attachment, linked record, formula, rollup, and more |
database_update_field | Renames a field or changes its options. The type cannot be changed |
database_delete_field | Deletes a field and its value in every record. The primary field cannot be deleted |
database_set_primary_field | Makes another field the table’s primary field |
database_list_views | Lists a table’s saved views, which can be passed to database_list_records to apply their filters and sorts |
database_create_view | Creates a saved view, optionally with hidden fields, sorting, grouping, and a filter |
Records
| Tool | What it does |
|---|---|
database_list_records | Lists records, optionally through a saved view |
database_search_records | Finds records using filter conditions and sorting |
database_get_record | Gets a single record by ID |
database_create_record | Creates one record |
database_create_records | Creates up to 100 records in one call |
database_update_record | Updates fields on a record, leaving the others untouched |
database_delete_record | Deletes one record |
database_delete_records | Deletes up to 100 records in one call |
The primary field is a record’s name: Softr shows it in record pickers and in the tables that link to this one. database_set_primary_field accepts text, email, phone, URL, number, date, created time, formula, autonumber, and record ID fields. The old primary field stays in the table as an ordinary field. A common use is a record people refer to by a key such as “BUG-12”: an autonumber field, a formula field that builds the key from it, and that formula made primary.
Attachments
| Tool | What it does |
|---|---|
database_attach_file_from_url | Adds a file to a record’s attachment field from a URL |
database_create_attachment_upload_link | Creates a link to upload files from your computer to a record’s attachment field |
Both add files and keep the ones already in the field. database_attach_file_from_url downloads the file and stores Softr’s own copy, so the attachment keeps working after the URL stops. The URL has to return the file itself: a Google Drive or Dropbox share page returns a web page, so use its direct download link.
For a file on your computer, the assistant uploads it through the link itself if it can run commands, and otherwise gives you the link to open in a browser and drop the file on. One link takes up to 10 files of up to 25 MB each.
Analytics
| Tool | What it does |
|---|---|
database_aggregate_records | Groups and summarizes a table with sum, average, count, min, max, or distinct count |
database_aggregate_records returns totals rather than rows, which makes it the right tool behind questions like “revenue by month” or “how many open tickets per assignee”. It groups by at most two fields.
Deleting data
Deletes are permanent. Nothing is kept in a trash you can restore from, so the assistant should tell you exactly what it is about to remove and wait for your go-ahead.
A few rules apply, and they exist so an assistant cannot quietly take more than you meant.
Deleting something that still holds data takes a second, explicit attempt. A database with tables in it, or a table with records in it, is refused the first time: the response says how much is inside, and the assistant has to repeat the call with a force flag to go through with it. Empty ones are deleted straight away. The refusal is a speed bump rather than a guarantee — a well-behaved assistant relays the count and asks you before retrying, and a count of 4,000 records is your cue to check it is the right table.
A database always keeps at least one table. Deleting a database’s only table is refused outright, and force does not override it — the same rule the builder applies. If you want the last table gone, what you actually want is the database gone, so ask for that instead and the table goes with it.
A table always keeps its primary field. Every other field can be deleted. To remove the current primary field, make another field primary with database_set_primary_field first. Deleting a field removes its values from every record, drops it from any view’s filters and sorts, and marks formulas that referenced it invalid.
Two things are not tidied up for you when a field goes. Deleting a linked record field leaves the matching field on the other table in place, still pointing at a relationship that no longer exists — remove it separately if the relationship is going away for good. Lookups and rollups that read through the deleted field are also left as they were. Worth checking what depends on a field before you remove it.
Batch record deletes are lenient about IDs. database_delete_records takes up to 100 record IDs. IDs that no longer exist are skipped rather than failing the whole batch, and the result tells you how many records were actually deleted, so “deleted 8 of 10” means two were already gone.
Limits
Records per database_create_records call | 100 |
Record IDs per database_delete_records call | 100 |
| Records returned per read | 200 |
Group-by fields in database_aggregate_records | 2 |
Asking for more than 200 records is not an error — you simply get 200. Reading a large table therefore takes several calls, which is another reason to prefer a filter or an aggregate over paging through everything.