Data

The four Data steps read and write the rows of your tables through the same engine as the Data API. They act as the run's executor: its permissions, row filters, field grants and payload checks apply, and PostgreSQL's constraints and triggers decide as for any other write. A step never writes anything the executor couldn't write through the API.

Each step names its table by its identity, not its name: renaming the table in PostgreSQL keeps the step working, while dropping it and creating another with the same name doesn't silently retarget it. Publishing refuses a step whose table no longer exists.

Read records

The executor needs READ. Their row filter and field grants apply; password columns are never returned. The Data API's limits apply too: without a limit, the default page size (api.default_limit) is read, never more than api.max_limit. Read nothing more than a step needs.

An empty result is a success: check it with a Condition, such as {"length": {"_eq": "0"}} on {{read_orders.data}}.

Acme's Service request intake finds the site of the customer who wrote in:

{
  "fields": "id,branch,customer",
  "where": { "customer.email": { "_eq": "{{start.data.body.email}}" } },
  "limit": 1
}

The next step reads the site as {{find_site.data[0].id}}.

Create records

[
  {
    "site": "{{find_site.data[0].id}}",
    "branch": "{{find_site.data[0].branch}}",
    "type": "REPAIR",
    "priority": "NORMAL",
    "status": "NEW",
    "description": "{{start.data.body.description}}"
  }
]

All the records are created in one transaction: if PostgreSQL refuses one, such as a failed CHECK or a missing required column, none is created and the step fails with PostgreSQL's message. Columns PostgreSQL fills, such as id, number or due_at at Acme, come back in the result: {{create_order.data[0].number}}.

Records may also be a single {{…}} that resolves to a list, such as the rows a Parse CSV step produced.

Update records

The update is checked like any Data API update: the executor's row filter must allow each row before and after the change, and their payload checks must hold. All rows change in one transaction, or none does. No row matching is a success, with an empty result.

A step with no filter would update every row the executor may update. While Require a filter for bulk update (api.require_where_for_update) is on, the default, such a step can't be published, and fails if the setting is turned on later.

Delete records

All rows are deleted in one transaction. The result is the deleted rows, as they were.

Audit and events

Every write is in the audit log like any other: the executor as who did it, workflow as where it came from, and the run and step it belongs to. Audit entries in a run's detail opens them.

Emit database events

A write by a workflow starts Database event workflows only when its step's Emit database events is on. Leave it off unless another workflow should react to this write. When it's on, TotalBase still refuses a workflow that would start itself again, directly or through others, and chains longer than workflows.max_chain_depth workflows (8 by default).

Execute SQL and Execute function never produce database events.

Errors

Connect the step's Error output to handle them; see Errors.

Next steps

• Control: branch on what you read.
• Values: {{…}} in Records, Set and filters.