botbook/src/06-gbdialog/keyword-merge.md

MERGE

Combines data from multiple sources or upserts records into a database table.

Syntax

MERGE table, data, key_column
MERGE table, data, key_columns, update_columns

Parameters

Parameter	Type	Description
table	String	Target database table name
data	Array/Object	Data to merge (single record or array of records)
key_column	String	Column(s) to match existing records
update_columns	Array	Optional specific columns to update on match

Description

MERGE performs an "upsert" operation: it inserts new records or updates existing ones based on matching key columns. This is useful for synchronizing data from external sources, importing bulk data, or maintaining data consistency.

Examples

Basic Merge (Single Record)

contact = #{
    email: "john@example.com",
    name: "John Smith",
    phone: "+1-555-0123"
}

MERGE "contacts", contact, "email"
TALK "Contact merged successfully"

Bulk Merge

new_products = GET "https://api.supplier.com/products"

MERGE "products", new_products, "sku"
TALK "Merged " + LEN(new_products) + " products"

Merge with Specific Update Columns

price_updates = [
    #{sku: "ABC123", price: 29.99},
    #{sku: "DEF456", price: 49.99},
    #{sku: "GHI789", price: 19.99}
]

MERGE "products", price_updates, "sku", ["price"]
TALK "Prices updated"

Composite Key Match

attendance = #{
    employee_id: "EMP001",
    date: TODAY(),
    status: "present",
    check_in: NOW()
}

MERGE "attendance", attendance, "employee_id,date"

Sync from External API

SET SCHEDULE "every 6 hours"

' Fetch latest data from CRM
customers = GET "https://crm.example.com/api/customers"

' Merge into local database
MERGE "customers", customers, "crm_id"

TALK "Synced " + LEN(customers) + " customer records"

Return Value

Returns an object with merge statistics:

Property	Description
inserted	Number of new records created
updated	Number of existing records updated
unchanged	Number of records that matched but had no changes
total	Total records processed

result = MERGE "products", data, "sku"
TALK "Inserted: " + result.inserted + ", Updated: " + result.updated

Sample Conversation

Sync customer data from the CRM

14:00

🔄 Syncing customer data...

14:00

✅ Customer sync complete!

📊 Results:

• New customers: 12

• Updated records: 45

• Unchanged: 238

• Total processed: 295

14:01

Behavior

On Match (Key Exists)

• Updates all columns in the data (or only update_columns if specified)
• Preserves columns not in the data
• Updates updated_at timestamp if column exists

On No Match (New Record)

• Inserts new row with all provided columns
• Sets created_at timestamp if column exists

Common Patterns

Daily Data Import

SET SCHEDULE "every day at 2am"

data = GET "https://data.provider.com/daily-export"
result = MERGE "imported_data", data, "external_id"

IF result.inserted > 0 THEN
    SEND MAIL "admin@company.com", "Data Import", 
        "Imported " + result.inserted + " new records"
END IF

Inventory Sync

inventory = GET "https://warehouse.api/stock-levels"
MERGE "products", inventory, "sku", ["quantity", "last_restock"]

User Profile Updates

profile = #{
    user_id: current_user_id,
    preferences: user_preferences,
    last_active: NOW()
}
MERGE "user_profiles", profile, "user_id"

See Also

• INSERT - Insert new records only
• UPDATE - Update existing records only
• SAVE - Simple data persistence
• FIND - Query data before merging

---