> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Database Node

> Add, find, change and delete rows in your agent's Database from a workflow, or run SQL with parameters.

The Database step works with a [Database store](https://docs.cogniagent.ai/features/databases.md) of the agent the workflow belongs to. Save a new lead, look up an order, update a status, or run a query, without leaving the workflow.

## When to use

* **Save a record**: a lead from a form, an order from a webhook
* **Look something up** before deciding what to do next
* **Update a row** when a status changes
* **Go through many rows** with a [Loop](https://docs.cogniagent.ai/nodes/logic/loop.md)
* **Total or join** with a SQL query

## Operations

Pick the **Database store** and the **Operation**. The form shows only the settings that operation uses.

| Operation | What it does | Gives back |
| - | - | - |
| **Insert** | Add a row to a table | The new row |
| **Get** | Read one row by its `id` | `row` |
| **Find** | Read rows that match a filter, sorted and limited | `rows`, `nextCursor`, `truncated` |
| **Update** | Change one row by `id`, or every row a filter matches | `changes` |
| **Delete** | Delete one row by `id` | `changes` |
| **SQL** | Run one statement with parameters | `columns` and `rows`, or `changes` |

Every value field takes `{{…}}` from earlier steps, including `{{agent.…}}`.

## Filter and sort

**Find** and **Update** take a filter as a list of conditions on columns. Use `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `like` and `is_null`:

```json theme={null}
{ "status": "open", "amount": { "gt": 100 } }
```

An **Update** by filter needs a filter. It never changes every row by accident.

**Find** returns up to the limit you set. When `truncated` is `true`, more rows match. Pass `nextCursor` back in a second Find step to read the next page.

## SQL

Choose **SQL** to write the statement yourself, and choose **Read** or **Write** mode. Put values in **Parameters**, not in the text:

```sql theme={null}
SELECT id, total FROM orders WHERE customer_email = ? AND total > ?
```

with the parameters `{{start_1.email}}` and `100`. The statement itself is never filled in from earlier steps. This keeps a customer's text from changing what the query does.

## Example: save a lead and tell the team

**1. Take the lead**

A [Webhook](https://docs.cogniagent.ai/nodes/triggers/webhook.md) starts the workflow with a name and an email.

**2. Check for a duplicate**

A Database step, **Find**, table `leads`, filter `{"email": "{{start_1.email}}"}`.

**3. Save it if new**

A [Condition](https://docs.cogniagent.ai/nodes/logic/condition.md) on `{{database_1.rows.length}}`. On the new branch, a Database step, **Insert**, table `leads`, with the name and email.

## When things go wrong

| What you see | Why |
| - | - |
| The store isn't in the list | The agent has no Database yet, or the database service isn't switched on for you |
| A table or column error | The name doesn't match the designer. Check the store's page |
| The step says the write may have been applied | The call timed out. Check the rows before you retry |
| The service is busy | Too many requests at once. The step fails, and a retry usually works |
| A database from another agent isn't found | Stores of other agents can't be reached. Expose it and use an HTTP Request instead |

## Used as a tool

When an [LLM](https://docs.cogniagent.ai/nodes/actions/llm.md) step uses this step as a tool, pin one operation in the step first. The AI then picks the values, never the operation.

## Settings

**storeKey** `string` *required*

The **Database store**, by its key.

**operation** `string` *required*

`insert`, `get`, `find`, `update`, `delete` or `sql`.

**table** `string`

The table, for every operation except SQL.

**rowId** `number`

The row's `id`, for get, update and delete.

**filter** `object`

Conditions for find and update.

**sql** `string`

The statement, for SQL. Never filled in from earlier steps.

**params** `array`

The values for the statement's placeholders.

**mode** `string` (default: read)

`read` or `write`, for SQL. Never filled in from earlier steps.

## Next steps

> [card] [Database](https://docs.cogniagent.ai/features/databases.md)
>
> Tables, the designer and the SQL console.

> [card] [Loop](https://docs.cogniagent.ai/nodes/logic/loop.md)
>
> Go through the rows a Find returns.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.