Update Database - Synthreo Builder

---

Purpose

The Update Database node writes input data from the workflow into a connected database table. It supports inserting new records, inserting only when no matching record exists, and updating existing records based on a key column - all without writing SQL. Use it to persist AI-processed results, synchronize data from external sources, log workflow activity, or maintain master data in your databases.

---

Configuration

Database Connection

Field	Description
Database	Select a connected database system configured in your ThreoAI credentials. Only databases that have been set up in the platform appear here.
Table	Choose the target table within the selected database. The table must already exist in the database.

---

Operation Mode

The Database Operation field determines how data is written.

Operation	Description	When to use
Insert	Adds a new record to the table every time the node runs, regardless of whether a matching record already exists.	Logging events, appending transaction records, building audit trails, or any scenario where duplicate records are acceptable.
Insert only if not exists	Adds a new record only when no existing record matches the incoming data. Uses the Exclude Properties setting to define which fields are checked for duplicates.	Seeding reference data, syncing product catalogs, importing records from external sources where duplicates would cause problems.
Update with value	Finds an existing record using the Key Column Name and updates its fields with the incoming data. If no matching record is found, behavior depends on the database configuration.	Refreshing customer information, updating status fields, maintaining current state for entities that already exist in the database.

---

Operation-Specific Settings

Field	Applies to	Description
Exclude Properties	Insert only if not exists	Comma-separated list of field names to ignore during the duplicate check. Properties listed here are not compared when determining whether a matching record already exists. Use this to exclude fields like timestamps or generated IDs that would always differ between records even when the core data is the same.
Clear Table Before Insert	Insert	When enabled, truncates (clears all rows from) the target table before inserting new records. Use with caution - this is a destructive operation that permanently removes all existing data from the table. Suitable for workflows that replace an entire dataset (e.g., refreshing a daily report table).
Key Column Name	Update with value	The name of the database column used to identify which record to update. The node matches the incoming data’s value for this column against existing rows to find the target record. Must match an actual column name in the table exactly (case-sensitive). Example: customer_id, order_number, sku.

---

Data Mapping

The Properties section maps workflow fields to database columns. Each row in the mapping defines:

Field	Description
Name	The name of the property in the workflow input (the key in the incoming data object).
Save Into	The name of the database table column where that value should be stored.

You can map as many fields as needed. Only the fields defined in the mapping are written to the database - any fields in the workflow input that are not mapped are ignored.

Example mapping for a customer update:

Name (workflow property)	Save Into (database column)
customerId	customer_id
fullName	customer_name
emailAddress	email
lastModified	updated_at

---

Output

This node produces no output variable. It writes data directly to the database and then passes execution to the next node. If downstream nodes need confirmation that the write succeeded, use error handling or a subsequent database read to verify.

---

Common Use Cases

Scenario	Operation	Configuration
Order Processing	Insert	Map order fields to the orders table. Every workflow run creates a new order record.
Daily Report Refresh	Insert + Clear Table Before Insert	Clears the prior day’s data and inserts the latest results. The table always contains only the most recent report.
Customer Profile Updates	Update with value	Set Key Column Name to customer_id. The node finds the customer and updates only the mapped fields.
Product Catalog Sync	Insert only if not exists	Imports new products from a supplier feed. Products already in the catalog are skipped; only new SKUs are added.
Activity Logging	Insert	Appends a row for every workflow execution. Builds a full audit trail over time.
Status Tracking	Update with value	Updates a status column and updated_at timestamp on an existing record when an AI agent completes a task.

---

Best Practices

• Mapping accuracy: Verify that field names in the Name column match the actual property names in your workflow data exactly (case-sensitive). Mismatches cause fields to be silently skipped.
• Operation choice: Choose Insert for append-only logging, Insert only if not exists for idempotent sync operations, and Update with value for maintaining current entity state.
• Key column integrity: For Update operations, ensure the Key Column Name column exists in the table and contains values that uniquely identify records. Using a non-unique column causes unpredictable update behavior.
• Clear Table caution: Never enable Clear Table Before Insert on tables containing data that cannot be recreated. Test on a development database before using in production.
• Testing: Always test with a small sample of data in a non-production environment before running against production tables. Verify that records are created, skipped, or updated as expected.
• Performance: Avoid clearing large tables during peak operating hours. Schedule such operations for off-peak times.

---

Test Cases

• Given: Insert mode with valid field mapping - Expected: A new record is created in the database containing the mapped values.
• Given: Insert only if not exists, with a record that already exists in the table - Expected: No duplicate record is created; the existing record is unchanged.
• Given: Update with value, Key Column Name = customer_id, incoming data matches an existing row - Expected: The existing row is updated with the new field values from the workflow.
• Given: Clear Table Before Insert enabled - Expected: All existing rows are removed before the new record is inserted.

---

Quick Start

1. Add the Update Database node to your workflow.
2. Select your connected database and the target table.
3. Choose an operation type based on your use case.
4. Configure any operation-specific settings (Key Column Name, Exclude Properties, or Clear Table).
5. Map each workflow field to its corresponding database column in the Properties section.
6. Run a test workflow with sample data and verify that the database is updated as expected.