Read Database

Controlled node

Overview

The Read Database node retrieves rows from a specified table in a project database. It supports filtering by specific row IDs or by matching column values, making it ideal for fetching existing data to process within your workflow.

By default, the node returns all rows from the specified table if no filter criteria is provided. For large datasets, consider using the Query Database node with explicit limit and offset parameters for better performance.

Inputs

Input	Type	Description	Default
Run	Event	Triggers the database read operation.	-
Database ID	Data	The unique identifier of the project database to read from.	-
Table ID	Data	The name or identifier of the table within the database.	-
Rows	Data	Optional filter criteria. Can be an array of objects (row matchers), a single object, an array of strings (treated as intellectible_ids), or a single string (treated as an intellectible_id). If omitted, returns all rows.	-

Outputs

Output	Type	Description
Done	Event	Fires when the database read operation completes successfully.
Result	Data	An array containing the matching rows from the database. Returns an empty array if no matches found.

Runtime Behavior and Defaults

When triggered, the node validates that the Database ID and Table ID are valid strings and that the project context is available.

Row Matching Logic:

• Object filters: When you provide an object (or array of objects), the node returns rows where all specified columns match the provided values exactly.
• String filters: When you provide a string (or array of strings), the node treats these as intellectible_id values and returns the corresponding rows.
• No filter: If the Rows input is empty or not connected, the node attempts to return all rows from the table (subject to platform limits).

Error Handling: If validation fails or the database operation encounters an error, the Result output will contain an error object with an error property describing the issue.

Example Usage

Basic Row Retrieval:

1. Connect a Start node to the Run input of the Read Database node.
2. Set the Database ID and Table ID using the node's UI panel (which provides dropdown selectors for available databases and tables).
3. Connect the Result output to a Show node to inspect the retrieved data.

Filtered Retrieval by ID: Connect a Text node containing a specific row ID (e.g., "row-123") to the Rows input to retrieve only that specific row.

Filtered Retrieval by Column Values: Connect a Dictionary node containing {"status": "active", "priority": "high"} to the Rows input to retrieve only rows where both the status column equals "active" AND the priority column equals "high".

Processing Results: Connect the Result output to a For Each node to iterate through the returned rows and process each one individually.