Querying from agents and workflows

Workflows reach a database through a Database step. Agents reach the databases granted to them on their editor. Both work on the same tables you see in the explorer.

From	Statements per call	Writes	Rows returned, at most
A Database step	One	Yes	256 KiB
An agent	One	Only with Allow writes	64 KiB
The explorer, API	Up to 100	Yes	16 MiB

A result over the cap is refused with “Add a LIMIT or select fewer columns.”

From a workflow: the Database step

Add a Database node in the builder. Its panel has two fields:

Field	What it holds
Database (required)	One of your organization’s databases.
SQL (required)	One SQLite statement. As you type, it suggests the database’s tables and columns and the {{ }} variables.

The step can read and write. For example:

insert into tickets (subject, sender) values ({{ trigger.subject }}, {{ trigger.from }})

How {{ }} values go in

Each {{ }} in the SQL becomes a bound parameter, with its filters applied. The value is never pasted into the statement’s text, so a quote inside it can’t change the query.

• Don’t wrap a {{ }} in quotes. Write {{ trigger.name }}, not '{{ trigger.name }}'. The quotes would turn the placeholder into plain text.
• A {{ }} stands only where SQLite accepts a value. It can’t supply a table name, a column name or a keyword.
• {% %} tags such as if and for are refused with “SQL templates take values only, no tags”. Prepare the value in an earlier step instead.

The value is	It binds as
Text or a number	Itself
true or false	1 or 0
A list or object	Its JSON, as text
Missing	null

See Templates and variables for the variables and filters.

What the step outputs

Output	Variable	Contents
Rows	{{ nodes.<id>.rows }}	The rows, each keyed by column name
Columns	{{ nodes.<id>.columns }}	The column names, in order
Row count	{{ nodes.<id>.rowCount }}	How many rows the statement returned

The step’s text, which the next step reads, is the rows as JSON.

Publishing checks that the step has a database and SQL, and that the SQL has no tags. If the statement fails when the run reaches it, the step fails with SQLite’s message, and the run page shows it. The Database node page has the full reference.

From an agent

1. Open the agent’s page from Agents and go to the Editor tab.
2. Under Databases, press Add a database and pick one.
3. Turn on Allow writes for a database the agent may change. Leave it off to keep the agent read-only there.
4. Press Save changes.

The agent then has two tools for its databases:

Tool	What it does
describe_database	Returns one database’s schema as its CREATE statements: tables, indexes, views and triggers.
query_database	Runs one SQLite statement, with ? placeholders and the values passed separately, and returns the rows.

Each tool’s description lists the agent’s databases by name and description, marking the read-only ones. On a database without Allow writes, a statement that writes a row or changes the schema is rolled back, and the agent is told the database is read-only here.

The agent has the same databases in chat and when an Agent step runs it in a workflow.

Caution

Database writes don’t wait for approval. Approvals cover the app actions an agent’s grants mark to ask first (see Grants and approvals). An agent with Allow writes can change that database on any turn. Turn it on only where the agent should change data, and say in its instructions when it may write.

Write the instructions around the data

Instructions can read the databases variable, each with its name and whether it is writable. On the Editor tab, Start from a template offers Data analyst: it names the read-only and writable databases and tells the agent to show the statement and ask before any INSERT, UPDATE or DELETE. That is an instruction to the agent, not a check Super Flows enforces. See Creating an agent.

From the API

An organization key runs SQL on any of the organization’s databases. See Databases.