delete
Permanently remove database records by ID, including connected relations and triggering deletion events. This irreversible operation also handles foreign key constraint validation.
Instructions
Delete a specific record from the database by its ID.
This tool permanently removes a record from the database. Use with caution as this operation cannot be undone. The deletion will also:
Remove any graph edges (relations) connected to this record
Trigger any defined deletion events/hooks
Fail if the record is referenced by FOREIGN KEY constraints
Args: thing: The full record ID to delete in format "table:id" (e.g., "user:john", "product:laptop-123")
Returns: A dictionary containing: - success: Boolean indicating if deletion was successful - deleted: The ID of the deleted record - data: The deleted record data (if available) - error: Error message if deletion failed (only present on failure)
Examples: >>> await delete("user:john") {"success": true, "deleted": "user:john", "data": {"id": "user:john", "name": "John Doe"}}
Note: This operation is irreversible. Consider using soft deletes (status fields) for recoverable deletions.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| thing | Yes |
Implementation Reference
- surreal_mcp/server.py:356-419 (handler)Handler function for the 'delete' tool. Decorated with @mcp.tool() for registration. Validates input, fetches record data before deletion, calls repo_delete helper, and returns formatted response.@mcp.tool() async def delete( thing: str, namespace: Optional[str] = None, database: Optional[str] = None, ) -> Dict[str, Any]: """ Delete a specific record from the database by its ID. This tool permanently removes a record from the database. Use with caution as this operation cannot be undone. The deletion will also: - Remove any graph edges (relations) connected to this record - Trigger any defined deletion events/hooks - Fail if the record is referenced by FOREIGN KEY constraints Args: thing: The full record ID to delete in format "table:id" (e.g., "user:john", "product:laptop-123") 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 deletion was successful - deleted: The ID of the deleted record - data: The deleted record data (if available) - error: Error message if deletion failed (only present on failure) Examples: >>> await delete("user:john") {"success": true, "deleted": "user:john", "data": {"id": "user:john", "name": "John Doe"}} >>> await delete("product:nonexistent") {"success": true, "deleted": "product:nonexistent", "data": null} # No error even if record didn't exist Note: This operation is irreversible. Consider using soft deletes (status fields) for recoverable deletions. """ try: ns, db = resolve_namespace_database(namespace, database) # Validate thing format if ":" not in thing: raise ValueError(f"Invalid record ID format: {thing}. Must be 'table:id'") logger.info(f"Deleting record {thing}") # Try to get the record first (optional, for returning deleted data) try: select_result = await repo_query(f"SELECT * FROM {thing}", namespace=ns, database=db) deleted_data = select_result[0] if select_result else None except Exception: deleted_data = None # Perform the deletion record_id = ensure_record_id(thing) await repo_delete(record_id, namespace=ns, database=db) return { "success": True, "deleted": thing, "data": deleted_data } except Exception as e: logger.error(f"Delete failed for {thing}: {str(e)}") raise Exception(f"Failed to delete {thing}: {str(e)}")
- Core database deletion helper called by the delete tool handler. Uses the connection pool to execute the DELETE operation on SurrealDB.async def repo_delete( record_id: Union[str, RecordID], namespace: Optional[str] = None, database: Optional[str] = None, ): """Delete a record by record id. Args: record_id: The record ID to delete namespace: Optional namespace override (uses env var if not provided) database: Optional database override (uses env var if not provided) Returns: The deletion result """ try: async with db_connection(namespace, database) as connection: return await connection.delete(record_id) except Exception as e: logger.exception(e) raise RuntimeError(f"Failed to delete record: {str(e)}")
- Utility helper to normalize record ID strings into RecordID objects, used in the delete handler.def ensure_record_id(value: Union[str, RecordID]) -> RecordID: """Ensure a value is a RecordID.""" if isinstance(value, RecordID): return value return RecordID.parse(value)
- surreal_mcp/server.py:371-375 (schema)Input/output schema defined in the docstring of the delete handler, specifying parameters, types, and response format.Args: thing: The full record ID to delete in format "table:id" (e.g., "user:john", "product:laptop-123") 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.
- surreal_mcp/server.py:356-356 (registration)@mcp.tool() decorator registers the delete function as an MCP tool.@mcp.tool()