Skip to main content

Start Merge

Starts a merge operation for atomic increment, decrement, or JSON merging on a specific key in BadgerDB.

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​

  • Database Id - The unique identifier of the database, as returned by the Open node.
  • Key - The key on which to perform merge operations.

Options​

  • Operation Type - The type of merge operation to perform:
    • Increment - Atomically add integer values to the key
    • Decrement - Atomically subtract integer values from the key
    • JSON - Merge JSON objects together

Output​

  • Merge ID - A unique identifier for the started merge operation. Use this ID in Merge and Stop Merge nodes.

How It Works​

The Start Merge node initializes a merge operator that allows multiple values to be combined atomically. Unlike regular transactions, merge operations are designed for specific use cases like counters and object merging.

When executed, the node:

  1. Validates the database ID and key
  2. Creates a merge operator with the specified operation type
  3. Returns a unique merge ID
  4. Keeps the merge operator active until stopped

Merge Operation Types​

Increment​

  • Adds integer values together
  • Perfect for counters and statistics
  • Example: Page views, API calls, item counts

Decrement​

  • Subtracts integer values
  • Useful for inventory, quotas
  • Example: Stock levels, remaining credits

JSON​

  • Merges JSON objects
  • Combines object properties
  • Later values override earlier ones for duplicate keys

Examples​

Example 1: Page View Counter (Increment)​

Track page views with atomic increments:

1. Start Merge (Increment)
   Database Id: {{db_id}}
   Key: page:home:views
   Operation Type: Increment
   → merge_id

2. Merge (add 1 view)
   Merge Id: {{merge_id}}
   Value: 1

3. Merge (add another view)
   Merge Id: {{merge_id}}
   Value: 1

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

(Result: page:home:views incremented by 2)

Example 2: Inventory Decrement​

Decrease stock levels:

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

2. For each order_item in {{order}}:
   Merge
     Merge Id: {{merge_id}}
     Value: {{order_item.quantity}}

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

(Result: stock decreased by total quantity)

Example 3: JSON Object Merge​

Merge user settings:

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

2. Merge (theme setting)
   Merge Id: {{merge_id}}
   Value: {"theme": "dark"}

3. Merge (language setting)
   Merge Id: {{merge_id}}
   Value: {"language": "en"}

4. Merge (notifications)
   Merge Id: {{merge_id}}
   Value: {"notifications": true}

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

(Result: {"theme": "dark", "language": "en", "notifications": true})

Example 4: Statistics Aggregation​

Collect statistics from multiple sources:

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

2. For each server in {{servers}}:
   Get Server Requests
     → server_requests

   Merge
     Merge Id: {{merge_id}}
     Value: {{server_requests}}

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

Example 5: Concurrent Counter Updates​

Handle concurrent counter increments:

Flow 1:
  1. Start Merge
     Key: api:calls:count
     Operation Type: Increment
     → merge_id
  2. Merge (Value: 1)
  3. Stop Merge

Flow 2 (runs concurrently):
  1. Start Merge
     Key: api:calls:count
     Operation Type: Increment
     → merge_id
  2. Merge (Value: 1)
  3. Stop Merge

(Both increments are applied atomically)

Tips for Effective Use​

  • Use Increment for Counters - Atomic and efficient counter operations
  • Use Decrement for Quotas - Track remaining resources
  • Use JSON for Configuration - Merge settings from multiple sources
  • Multiple Merges - Call Merge multiple times before Stop Merge
  • Always Stop - Always call Stop Merge to finalize the operation
  • One Key Per Merge - Each merge operation works on a single key

Common Errors and Solutions​

Error: "database id cannot be empty"​

Solution: Ensure you're passing a valid database ID from the Open node.

Correct:
  Open → db_id
  Start Merge (Database Id: {{db_id}})

Error: "key cannot be empty"​

Solution: Provide a valid key for the merge operation.

Correct:
  Key: counter:page_views

Error: Invalid Operation Type​

Solution: Select a valid operation type:

  • Increment
  • Decrement
  • JSON

Increment vs. Decrement vs. JSON​

Increment​

  • Use for: Counters, totals, accumulation
  • Value type: Integer (positive numbers)
  • Operation: Addition
  • Example: Page views, API calls, clicks

Decrement​

  • Use for: Quotas, inventory, remaining items
  • Value type: Integer (positive numbers, result can be negative)
  • Operation: Subtraction
  • Example: Stock levels, credits, capacity

JSON​

  • Use for: Configuration, settings, metadata
  • Value type: JSON objects
  • Operation: Object merging (later values override)
  • Example: User preferences, feature flags, metadata

Merge vs. Transaction​

Merge Operations​

  • Purpose: Atomic increment/decrement/merge
  • Use case: Counters, aggregation, settings merge
  • Performance: Optimized for these specific operations
  • Concurrency: High concurrency support
  • Complexity: Simple API for common patterns

Transactions​

  • Purpose: General atomic operations
  • Use case: Complex multi-key updates
  • Performance: General-purpose
  • Concurrency: Standard transaction isolation
  • Complexity: More flexible but more complex

Use Merge for: Simple counters and merges Use Transactions for: Complex multi-key operations

Use Cases​

Use Case 1: API Rate Limiting​

Start Merge (Increment)
  Key: rate_limit:user:{{user_id}}:{{minute}}
Merge (Value: 1)
Stop Merge
Get rate_limit → count
If count > limit:
  Reject request

Use Case 2: Analytics​

For each event in {{analytics_events}}:
  Start Merge (Increment)
    Key: analytics:{{event.type}}:count
  Merge (Value: 1)
  Stop Merge

Use Case 3: Inventory Management​

Start Merge (Decrement)
  Key: inventory:{{product_id}}:quantity
For each order_item:
  Merge (Value: {{order_item.quantity}})
Stop Merge

Use Case 4: Configuration Merging​

Start Merge (JSON)
  Key: app:config
Merge (Value: default_config)
Merge (Value: environment_config)
Merge (Value: user_config)
Stop Merge

Performance Considerations​

  • Atomic Operations - Merge operations are atomic and thread-safe
  • High Concurrency - Designed for concurrent access
  • Efficient - Optimized for increment/decrement operations
  • Lock-Free - Uses optimistic concurrency control
  • Batching - Multiple Merge calls are batched efficiently

Best Practices​

  • Initialize Counters - Set initial value with Set node before using Increment
  • Check Result - Use Get to verify the merged value after Stop Merge
  • Handle Errors - Use try-catch to handle merge errors
  • Document Purpose - Comment why merge operations are used
  • One Operation Type - Don't mix operation types on the same key
  • Always Stop - Always call Stop Merge to finalize

Lifecycle​

Successful Merge​

Start Merge → Add Values (Merge) → Stop Merge → Value Updated

Abandoned Merge​

Start Merge → Add Values (Merge) → Flow Ends → Auto-Finalized
  • Merge - Adds values to the ongoing merge operation
  • Stop Merge - Finalizes and applies the merge operation
  • Set - Alternative for simple single-value updates
  • Start Transaction - Alternative for complex multi-key updates