Mutations

Learn how to create, update, and delete data with Query-2jz's mutation system.

What are Mutations?

Mutations in Query-2jz allow you to modify data in your models. They automatically handle validation, relationships, and provide optimistic updates for better user experience.

Mutation Features

Create operations

Update operations

Delete operations

Automatic validation

Optimistic updates

Transaction support

Create Operations

Create new records in your models using POST requests.

Create Single Record

Create a new record with validation

HTTP Request

POST /api/query-2jz/User

Request Body

json

{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "isActive": true
}

Response

json

{
  "data": {
    "id": "1",
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30,
    "isActive": true,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  },
  "success": true,
  "message": "User created successfully"
}

Bulk Create

Create multiple records in a single request

HTTP Request

POST /api/query-2jz/User/bulk

Request Body

json

{
  "data": [
    {
      "name": "John Doe",
      "email": "john@example.com"
    },
    {
      "name": "Jane Smith", 
      "email": "jane@example.com"
    }
  ]
}

Response

{
  "data": [
    {
      "id": "1",
      "name": "John Doe",
      "email": "john@example.com",
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "2",
      "name": "Jane Smith",
      "email": "jane@example.com", 
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "success": true,
  "message": "2 users created successfully"
}

Update Operations

Update existing records using PUT or PATCH requests.

Update Single Record

Update a specific record by ID

HTTP Request

PUT /api/query-2jz/User/1

Request Body

{
  "name": "John Updated",
  "age": 31,
  "isActive": false
}

Response

{
  "data": {
    "id": "1",
    "name": "John Updated",
    "email": "john@example.com",
    "age": 31,
    "isActive": false,
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T12:00:00Z"
  },
  "success": true,
  "message": "User updated successfully"
}

Partial Update (PATCH)

Update only specific fields

HTTP Request

PATCH /api/query-2jz/User/1

Request Body

{
  "isActive": false
}

Bulk Update

Update multiple records with conditions

HTTP Request

PUT /api/query-2jz/User/bulk

Request Body

{
  "where": {
    "status": "inactive"
  },
  "data": {
    "lastLoginAt": "2024-01-01T00:00:00Z"
  }
}

Response

{
  "data": {
    "updatedCount": 5
  },
  "success": true,
  "message": "5 users updated successfully"
}

Delete Operations

Delete records using DELETE requests with various options.

Delete Single Record

Delete a specific record by ID

HTTP Request

DELETE /api/query-2jz/User/1

Response

{
  "success": true,
  "message": "User deleted successfully"
}

Bulk Delete

Delete multiple records with conditions

HTTP Request

DELETE /api/query-2jz/User/bulk

Request Body

{
  "where": {
    "status": "inactive",
    "lastLoginAt": {"$lt": "2023-01-01"}
  }
}

Response

{
  "data": {
    "deletedCount": 10
  },
  "success": true,
  "message": "10 users deleted successfully"
}

Validation

Query-2jz automatically validates data based on your model definitions.

Validation Rules

Required Fields

{
  "name": { "type": "string", "required": true },
  "email": { "type": "email", "required": true }
}

Type Validation

{
  "age": { "type": "number", "min": 0, "max": 120 },
  "email": { "type": "email", "unique": true },
  "name": { "type": "string", "minLength": 2, "maxLength": 50 }
}

Custom Validation

{
  "password": {
    "type": "string",
    "validate": {
      "minLength": 8,
      "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$",
      "message": "Password must be at least 8 characters with uppercase, lowercase, and number"
    }
  }
}

Validation Error Response

{
  "success": false,
  "errors": [
    {
      "field": "email",
      "message": "Email is required",
      "code": "REQUIRED"
    },
    {
      "field": "age",
      "message": "Age must be between 0 and 120",
      "code": "RANGE_ERROR"
    }
  ],
  "message": "Validation failed"
}

Optimistic Updates

Query-2jz provides optimistic updates for better user experience.

How it Works

Client immediately updates UI with expected result
Mutation request is sent to server
If successful, UI remains updated
If failed, UI reverts to previous state with error message

Example Implementation

// Client-side optimistic update
const updateUser = async (userId, data) => {
  // Optimistically update UI
  setUsers(prev => prev.map(user => 
    user.id === userId ? { ...user, ...data } : user
  ));
  
  try {
    // Send mutation
    const result = await fetch(`/api/query-2jz/User/${userId}`, {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    });
    
    if (!result.ok) {
      throw new Error('Update failed');
    }
    
    // Success - UI already updated
  } catch (error) {
    // Revert optimistic update
    setUsers(prev => prev.map(user => 
      user.id === userId ? originalUser : user
    ));
    
    // Show error message
    showError('Failed to update user');
  }
};

Transactions

Ensure data consistency with transaction support.

// Transaction example
POST /api/query-2jz/transaction

{
  "operations": [
    {
      "type": "create",
      "model": "User",
      "data": {
        "name": "John Doe",
        "email": "john@example.com"
      }
    },
    {
      "type": "create", 
      "model": "Profile",
      "data": {
        "userId": "{{$1.id}}",  // Reference to first operation result
        "bio": "Software developer"
      }
    }
  ]
}