upsert
Create or update database records in SurrealDB. Insert new records when they don't exist, or merge data with existing records when they do.
Instructions
Upsert a record: create if it doesn't exist, merge/update if it does.
This tool is perfect when you want to ensure a record exists with specific data, regardless of whether it already exists. It will:
Create a new record with the specified ID if it doesn't exist
Merge the provided data into the existing record if it does exist
Always succeed (unless there's a database error)
Args: thing: The full record ID in format "table:id" (e.g., "user:john", "settings:global") data: The data for the record. If record exists, this will be merged with existing data namespace: Optional SurrealDB namespace override. If not provided, uses SURREAL_NAMESPACE env var. database: Optional SurrealDB database override. If not provided, uses SURREAL_DATABASE env var.
Returns: A dictionary containing: - success: Boolean indicating if upsert was successful - data: The record after upserting - created: Boolean indicating if a new record was created (vs updated) - error: Error message if upsert failed (only present on failure)
Examples: >>> await upsert("user:john", {"name": "John Doe", "email": "john@example.com"}) {"success": true, "data": {"id": "user:john", "name": "John Doe", ...}, "created": true}
>>> await upsert("user:john", {"email": "newemail@example.com"}) # Update existing
{"success": true, "data": {"id": "user:john", "name": "John Doe", "email": "newemail@example.com", ...}, "created": false}
>>> await upsert("settings:global", {"theme": "dark", "language": "en"})
{"success": true, "data": {"id": "settings:global", "theme": "dark", "language": "en"}, "created": true}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| thing | Yes | ||
| data | Yes | ||
| namespace | No | ||
| database | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||