Skip to main content

Merge

Adds a value to an ongoing merge operation started by Start Merge. Can be called multiple times to accumulate values.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.
info

If the ContinueOnError property is true, no error is caught when the project is executed, even if a Catch node is used.

Inputs​

  • Merge Id - The unique identifier of the merge operation, as returned by the Start Merge node.
  • Value - The value to add to the merge operation. The type depends on the operation type:
    • Increment/Decrement: Integer value to add/subtract
    • JSON: JSON object to merge

How It Works​

The Merge node adds a value to an ongoing merge operation. Values are accumulated and applied atomically when Stop Merge is called.

When executed, the node:

  1. Validates the merge ID
  2. Retrieves the merge operator
  3. Converts the value to the appropriate format (integer or JSON)
  4. Adds the value to the merge operator's buffer
  5. Waits for Stop Merge to apply all accumulated values

Examples​

Example 1: Increment Counter Multiple Times​

Increment a counter with multiple values:

1. Start Merge
   Database Id: {{db_id}}
   Key: total_requests
   Operation Type: Increment
   → merge_id

2. Merge (first batch)
   Merge Id: {{merge_id}}
   Value: 10

3. Merge (second batch)
   Merge Id: {{merge_id}}
   Value: 25

4. Merge (third batch)
   Merge Id: {{merge_id}}
   Value: 15

5. Stop Merge
   Merge Id: {{merge_id}}

(Result: total_requests increased by 50)

Example 2: Decrement in Loop​

Decrement inventory for multiple items:

1. Start Merge
   Database Id: {{db_id}}
   Key: product:SKU123:stock
   Operation Type: Decrement
   → merge_id

2. For each item in {{order_items}}:
   Merge
     Merge Id: {{merge_id}}
     Value: {{item.quantity}}

3. Stop Merge
   Merge Id: {{merge_id}}

Example 3: JSON Object Merging​

Merge multiple JSON objects:

1. Start Merge
   Database Id: {{db_id}}
   Key: user:1001:profile
   Operation Type: JSON
   → merge_id

2. Merge (basic info)
   Merge Id: {{merge_id}}
   Value: {
     "firstName": "John",
     "lastName": "Doe"
   }

3. Merge (contact info)
   Merge Id: {{merge_id}}
   Value: {
     "email": "john@example.com",
     "phone": "+1234567890"
   }

4. Merge (preferences)
   Merge Id: {{merge_id}}
   Value: {
     "theme": "dark",
     "language": "en"
   }

5. Stop Merge
   Merge Id: {{merge_id}}

(Result: All objects merged into single profile)

Example 4: Conditional Merge​

Add values based on conditions:

1. Start Merge
   Database Id: {{db_id}}
   Key: stats:error_count
   Operation Type: Increment
   → merge_id

2. For each log_entry in {{logs}}:
   If {{log_entry.level}} == "ERROR":
     Merge
       Merge Id: {{merge_id}}
       Value: 1

3. Stop Merge
   Merge Id: {{merge_id}}

Example 5: Aggregate from Multiple Sources​

Collect data from multiple endpoints:

1. Start Merge
   Database Id: {{db_id}}
   Key: analytics:total_users
   Operation Type: Increment
   → merge_id

2. For each region in {{regions}}:
   API Call: Get Users in {{region}}
     → user_count

   Merge
     Merge Id: {{merge_id}}
     Value: {{user_count}}

3. Stop Merge
   Merge Id: {{merge_id}}

Tips for Effective Use​

  • Call Multiple Times - Merge can be called many times before Stop Merge
  • Use in Loops - Perfect for accumulating values in loops
  • Integer Values - For Increment/Decrement, provide positive integers
  • JSON Objects - For JSON merge, provide valid JSON objects
  • Accumulation - All Merge calls accumulate until Stop Merge
  • Error Handling - Handle merge errors to prevent incomplete operations

Common Errors and Solutions​

Error: "merge id cannot be empty"​

Solution: Ensure you're passing the merge ID from Start Merge.

Correct:
  Start Merge → merge_id
  Merge (Merge Id: {{merge_id}})

Error: Merge Operator Not Found​

Solution: The merge operation doesn't exist. Ensure:

  • Start Merge was called successfully
  • Merge ID is correct
  • Merge operation wasn't already stopped

Error: "expected value to be an int64"​

Solution: For Increment/Decrement operations, provide an integer value.

Correct (Increment/Decrement):
  Value: 42
  Value: {{numeric_variable}}

Incorrect:
  Value: "text"
  Value: {"object": true}

Error: "failed to convert string to int64"​

Solution: When using Increment/Decrement, ensure the value can be converted to an integer.

Correct:
  Value: "123" → Converts to 123
  Value: 123 → Already an integer

Incorrect:
  Value: "abc" → Cannot convert

Error: JSON Marshal Error​

Solution: For JSON merge, provide valid JSON objects.

Correct (JSON Merge):
  Value: {"key": "value"}
  Value: {{json_object}}

Incorrect:
  Value: 123 (not an object)
  Value: "string" (not an object)

Operation Type Behavior​

Increment Operations​

  • Values are added together
  • All Merge calls sum up
  • Final result = initial value + sum of all merged values
  • Example: 0 + 10 + 20 + 30 = 60

Decrement Operations​

  • Values are subtracted
  • All Merge calls sum up and subtract
  • Final result = initial value - sum of all merged values
  • Example: 100 - 10 - 20 - 30 = 40

JSON Merge Operations​

  • Objects are merged together
  • Later values override earlier ones for duplicate keys
  • All objects combined into one
  • Example: {a:1} + {b:2} + {a:3} = {a:3, b:2}

Value Conversion​

Integer Conversion (Increment/Decrement)​

  • Integer values used directly
  • String numbers converted automatically ("123" → 123)
  • Float values converted to integers (123.7 → 123)

JSON Conversion​

  • JSON objects serialized automatically
  • JavaScript objects converted to JSON
  • Duplicate keys use last value

Use Cases​

Use Case 1: Multi-Source Counter​

Start Merge (Increment)
For each source:
  Get count from source
  Merge (Value: count)
Stop Merge

Use Case 2: Batch Inventory Update​

Start Merge (Decrement)
For each sold item:
  Merge (Value: item.quantity)
Stop Merge

Use Case 3: Configuration Builder​

Start Merge (JSON)
Merge (Value: default_config)
Merge (Value: environment_config)
If user_overrides_exist:
  Merge (Value: user_config)
Stop Merge

Use Case 4: Analytics Aggregation​

Start Merge (Increment)
For each hour in day:
  Get hourly stats
  Merge (Value: stats.page_views)
Stop Merge

Use Case 5: Dynamic Object Construction​

Start Merge (JSON)
Merge (Value: {id: user_id})
Merge (Value: {name: user_name})
If has_email:
  Merge (Value: {email: user_email})
If has_phone:
  Merge (Value: {phone: user_phone})
Stop Merge

Performance Considerations​

  • Efficient Batching - Multiple Merge calls are buffered efficiently
  • Memory Usage - Values buffered in memory until Stop Merge
  • No Disk I/O - No database writes until Stop Merge
  • Atomic Application - All values applied atomically at Stop Merge
  • Concurrency - Merge operators handle concurrent access

Best Practices​

  • Call in Loops - Perfect for accumulating values from iterations
  • Validate Values - Ensure values are correct type before merging
  • Handle Errors - Use try-catch for merge operations
  • Document Purpose - Comment what's being accumulated
  • Check Result - Use Get after Stop Merge to verify result
  • Consistent Types - Use same value type for all Merge calls

Merge Patterns​

Pattern 1: Simple Accumulation​

Start Merge → Merge (Value: 1) → Merge (Value: 2) → Stop Merge

Pattern 2: Loop Accumulation​

Start Merge
For each item:
  Merge (Value: item.count)
Stop Merge

Pattern 3: Conditional Accumulation​

Start Merge
For each record:
  If condition:
    Merge (Value: record.value)
Stop Merge

Pattern 4: Multi-Source Merge​

Start Merge
For each source:
  data = fetch_from_source()
  Merge (Value: data)
Stop Merge

JSON Merge Details​

Key Overriding​

Merge (Value: {a: 1, b: 2})
Merge (Value: {b: 3, c: 4})
Result: {a: 1, b: 3, c: 4}
(b was overridden)

Nested Objects​

Merge (Value: {user: {name: "John"}})
Merge (Value: {user: {email: "john@example.com"}})
Result: {user: {email: "john@example.com"}}
(Note: Nested merge replaces entire user object)

Array Handling​

Merge (Value: {items: [1, 2]})
Merge (Value: {items: [3, 4]})
Result: {items: [3, 4]}
(Arrays are replaced, not concatenated)
  • Start Merge - Starts the merge operation
  • Stop Merge - Finalizes and applies all merged values
  • Set - Alternative for single value updates
  • Get - Retrieves the final merged value