CRUD Operations

Master the four fundamental database operations: Create, Read, Update, and Delete across all platforms.

CRUD operations are the building blocks of any application. Cocobase makes them simple, intuitive, and consistent across all languages.

Overview

Cocobase provides type-safe, efficient CRUD operations for all supported platforms:

Create - Add new documents to collections
Read - Retrieve documents by ID or with filters
Update - Modify existing documents (partial or full)
Delete - Remove documents from collections
Batch Operations - Perform multiple operations at once

Create Documents

Add new documents to your collections with automatic ID generation and timestamp tracking.

Basic Creation

import { Cocobase } from 'cocobase';

const db = new Cocobase({ apiKey: 'your-api-key' });

// Create a single document with timestamps
const user = await db.createDocument('users', {
  name: 'John Doe',
  email: 'john@example.com',
  age: 30,
  active: true,
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
});

console.log('Created user:', user.id);

import { Cocobase } from 'cocobase';

interface User {
  name: string;
  email: string;
  age: number;
  active: boolean;
}

const db = new Cocobase({ apiKey: 'your-api-key' });

// TypeScript-style interface example in JS (for clarity)
const user = await db.createDocument('users', {
  name: 'Jane Smith',
  email: 'jane@example.com',
  age: 28,
  active: true,
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
});

console.log(user.data.name); // Type-safe structure assumed

import 'package:cocobase_flutter/cocobase_flutter.dart';

class User {
  final String name;
  final String email;
  final int age;
  final bool active;

  User({
    required this.name,
    required this.email,
    required this.age,
    required this.active,
  });

  factory User.fromJson(Map<String, dynamic> json) => User(
    name: json['name'],
    email: json['email'],
    age: json['age'],
    active: json['active'],
  );

  Map<String, dynamic> toJson() => {
    'name': name,
    'email': email,
    'age': age,
    'active': active,
  };
}

final db = Cocobase(CocobaseConfig(apiKey: 'your-api-key'));

// Type-safe document creation
final user = await db.createDocument<User>(
  'users',
  User(
    name: 'John Doe',
    email: 'john@example.com',
    age: 30,
    active: true,
  ).toJson(),
  converter: User.fromJson,
);

print('Created user: ${user.id}');
// user.data is typed as User

package main

import (
    "context"
    "fmt"
    "log"
    "github.com/lordace-coder/cocobase-go/cocobase"
)

func main() {
    client := cocobase.NewClient(cocobase.Config{
        APIKey: "your-api-key",
    })

    ctx := context.Background()

    // Create a single document
    data := map[string]interface{}{
        "name":   "John Doe",
        "email":  "john@example.com",
        "age":    30,
        "active": true,
    }

    doc, err := client.CreateDocument(ctx, "users", data)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Created user: %s\n", doc.ID)
}

from cocobase import Cocobase

db = Cocobase(api_key='your-api-key')

# Create a single document
user = db.create_document('users', {
    'name': 'John Doe',
    'email': 'john@example.com',
    'age': 30,
    'active': True
})

print(f"Created user: {user['id']}")

curl -X POST https://api.cocobase.buzz/collections/users/documents \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30,
    "active": true
  }'

Type-Safe Creation

JavaScript
Dart
Go
Python
HTTP

interface User {
  name: string;
  email: string;
  age: number;
  active: boolean;
}

const user = await db.createDocument<User>('users', {
  name: 'Jane Smith',
  email: 'jane@example.com',
  age: 28,
  active: true
});

// TypeScript knows the structure
console.log(user.data.name); // ✓ Type-safe

class User {
  final String name;
  final String email;
  final int age;
  final bool active;

  User({
    required this.name,
    required this.email,
    required this.age,
    required this.active,
  });

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      name: json['name'],
      email: json['email'],
      age: json['age'],
      active: json['active'],
    );
  }

  Map<String, dynamic> toJson() => {
    'name': name,
    'email': email,
    'age': age,
    'active': active,
  };
}

final user = await db.createDocument<User>(
  'users',
  User(
    name: 'Jane Smith',
    email: 'jane@example.com',
    age: 28,
    active: true,
  ).toJson(),
  converter: User.fromJson,
);

print('Created: ${user.data.name}');

type User struct {
    Name   string `json:"name"`
    Email  string `json:"email"`
    Age    int    `json:"age"`
    Active bool   `json:"active"`
}

data := map[string]interface{}{
    "name":   "Jane Smith",
    "email":  "jane@example.com",
    "age":    28,
    "active": true,
}

doc, err := client.CreateDocument(ctx, "users", data)
if err != nil {
    log.Fatal(err)
}

// Type assertion
if name, ok := doc.Data["name"].(string); ok {
    fmt.Printf("Created: %s\n", name)
}

from typing import TypedDict
from cocobase import Cocobase

class User(TypedDict):
    name: str
    email: str
    age: int
    active: bool

db = Cocobase(api_key='your-api-key')

user_data: User = {
    'name': 'Jane Smith',
    'email': 'jane@example.com',
    'age': 28,
    'active': True
}

user = db.create_document('users', user_data)
print(f"Created: {user['data']['name']}")

# HTTP requests are inherently untyped
# Use JSON schema validation if needed
curl -X POST https://api.cocobase.buzz/collections/users/documents \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "age": 28,
    "active": true
  }'

Batch Creation

Create multiple documents in a single operation for better performance.

JavaScript
Dart
Go
Python
HTTP

const users = await db.createDocuments('users', [
  {
    name: 'Alice',
    email: 'alice@example.com',
    age: 25,
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString()
  },
  {
    name: 'Bob',
    email: 'bob@example.com',
    age: 32,
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString()
  },
  {
    name: 'Charlie',
    email: 'charlie@example.com',
    age: 28,
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString()
  }
]);

console.log(`Created ${users.length} users`);

final users = [
  {'name': 'Alice', 'email': 'alice@example.com', 'age': 25},
  {'name': 'Bob', 'email': 'bob@example.com', 'age': 32},
  {'name': 'Charlie', 'email': 'charlie@example.com', 'age': 28},
];

for (var userData in users) {
  await db.createDocument('users', userData);
}

// Batch creation via API
users := []map[string]interface{}{
    {"name": "Alice", "email": "alice@example.com", "age": 25},
    {"name": "Bob", "email": "bob@example.com", "age": 32},
    {"name": "Charlie", "email": "charlie@example.com", "age": 28},
}

for _, userData := range users {
    _, err := client.CreateDocument(ctx, "users", userData)
    if err != nil {
        log.Printf("Error creating user: %v\n", err)
    }
}

users = [
    {'name': 'Alice', 'email': 'alice@example.com', 'age': 25},
    {'name': 'Bob', 'email': 'bob@example.com', 'age': 32},
    {'name': 'Charlie', 'email': 'charlie@example.com', 'age': 28}
]

# Create documents individually
for user_data in users:
    db.create_document('users', user_data)

print(f"Created {len(users)} users")

curl -X POST https://api.cocobase.buzz/collections/users/batch/documents \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {"name": "Alice", "email": "alice@example.com", "age": 25},
      {"name": "Bob", "email": "bob@example.com", "age": 32},
      {"name": "Charlie", "email": "charlie@example.com", "age": 28}
    ]
  }'

Read Documents

Retrieve documents by ID, or query collections with filters and pagination.

Get Single Document

JavaScript
Dart
Go
Python
HTTP

const user = await db.getDocument('users', 'user-123');
console.log(user.data);

final user = await db.getDocument('users', 'user-123');
print('User: ${user.data}');

doc, err := client.GetDocument(ctx, "users", "user-123")
if err != nil {
    if apiErr, ok := err.(*cocobase.APIError); ok {
        if apiErr.StatusCode == 404 {
            fmt.Println("Document not found")
            return
        }
    }
    log.Fatal(err)
}

fmt.Printf("User: %+v\n", doc.Data)

user = db.get_document('users', 'user-123')
print(f"User: {user['data']}")

curl https://api.cocobase.buzz/collections/users/documents/user-123 \
  -H "X-API-Key: your-api-key"

List All Documents

JavaScript
Dart
Go
Python
HTTP

const allUsers = await db.listDocuments('users');
console.log(`Total users: ${allUsers.length}`);

final allUsers = await db.listDocuments('users');
print('Total users: ${allUsers.length}');

docs, err := client.ListDocuments(ctx, "users", nil)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Total users: %d\n", len(docs))

all_users = db.list_documents('users')
print(f"Total users: {len(all_users)}")

curl https://api.cocobase.buzz/collections/users/documents \
  -H "X-API-Key: your-api-key"

With Filters

JavaScript
Dart
Go
Python
HTTP

// Get active users
const activeUsers = await db.listDocuments('users', {
  filters: { active: true }
});

// Get users older than 25
const olderUsers = await db.listDocuments('users', {
  filters: { age_gte: 25 }
});

// Multiple filters (AND logic)
const specificUsers = await db.listDocuments('users', {
  filters: {
    active: true,
    age_gte: 25,
    age_lte: 40
  }
});

// Get active users
final activeUsers = await db.listDocuments('users', filters: {
  'active': true,
});

// Get users older than 25
final olderUsers = await db.listDocuments('users', filters: {
  'age__gte': 25,
});

// Multiple filters (AND logic)
final specificUsers = await db.listDocuments('users', filters: {
  'active': true,
  'age__gte': 25,
  'age__lte': 40,
});

// Get active users
query := cocobase.NewQuery().Where("active", true)
activeUsers, err := client.ListDocuments(ctx, "users", query)

// Get users older than 25
query = cocobase.NewQuery().GreaterThanOrEqual("age", 25)
olderUsers, err := client.ListDocuments(ctx, "users", query)

// Multiple filters (AND logic)
query = cocobase.NewQuery().
    Where("active", true).
    GreaterThanOrEqual("age", 25).
    LessThanOrEqual("age", 40)
specificUsers, err := client.ListDocuments(ctx, "users", query)

# Get active users
active_users = db.list_documents('users', filters={
    'active': True
})

# Get users older than 25
older_users = db.list_documents('users', filters={
    'age__gte': 25
})

# Multiple filters (AND logic)
specific_users = db.list_documents('users', filters={
    'active': True,
    'age__gte': 25,
    'age__lte': 40
})

# Get active users
curl "https://api.cocobase.buzz/collections/users/documents?active=true" \
  -H "X-API-Key: your-api-key"

# Get users older than 25
curl "https://api.cocobase.buzz/collections/users/documents?age_gte=25" \
  -H "X-API-Key: your-api-key"

# Multiple filters (AND logic)
curl "https://api.cocobase.buzz/collections/users/documents?active=true&age_gte=25&age_lte=40" \
  -H "X-API-Key: your-api-key"

With Pagination

JavaScript
Go
Python
HTTP

// First page (10 users)
const page1 = await db.listDocuments('users', { limit: 10, offset: 0 });

// Second page
const page2 = await db.listDocuments('users', { limit: 10, offset: 10 });

// Helper for any page
function getPage(pageNumber, pageSize = 10) {
  return db.listDocuments('users', {
    limit: pageSize,
    offset: (pageNumber - 1) * pageSize
  });
}

const page3 = await getPage(3); // Users 21-30
``
</Tab>

<Tab title="Dart">
```dart
// Get first page (10 users)
final page1 = await db.listDocuments('users', filters: {
  'limit': 10,
  'offset': 0,
});

// Get second page
final page2 = await db.listDocuments('users', filters: {
  'limit': 10,
  'offset': 10,
});

// Using QueryBuilder
final page3 = await db.listDocuments(
  'users',
  queryBuilder: QueryBuilder().limit(10).offset(20),
);

// Get first page (10 users)
query := cocobase.NewQuery().Limit(10).Offset(0)
page1, err := client.ListDocuments(ctx, "users", query)

// Get second page
query = cocobase.NewQuery().Limit(10).Offset(10)
page2, err := client.ListDocuments(ctx, "users", query)

// Helper function
func getPage(client *cocobase.Client, page, perPage int) ([]cocobase.Document, error) {
    query := cocobase.NewQuery().
        Limit(perPage).
        Offset((page - 1) * perPage)

    return client.ListDocuments(ctx, "users", query)
}

page3, err := getPage(client, 3, 10) // Users 21-30

# Get first page (10 users)
page1 = db.list_documents('users', filters={
    'limit': 10,
    'offset': 0
})

# Get second page
page2 = db.list_documents('users', filters={
    'limit': 10,
    'offset': 10
})

# Helper function
def get_page(page_number, page_size=10):
    return db.list_documents('users', filters={
        'limit': page_size,
        'offset': (page_number - 1) * page_size
    })

page3 = get_page(3)  # Users 21-30

# Get first page (10 users)
curl "https://api.cocobase.buzz/collections/users/documents?limit=10&offset=0" \
  -H "X-API-Key: your-api-key"

# Get second page
curl "https://api.cocobase.buzz/collections/users/documents?limit=10&offset=10" \
  -H "X-API-Key: your-api-key"

# Get page 3
curl "https://api.cocobase.buzz/collections/users/documents?limit=10&offset=20" \
  -H "X-API-Key: your-api-key"

Update Documents

Modify existing documents with partial or full updates.

Basic Update

JavaScript
Dart
Go
Python
HTTP

// Partial update
await db.updateDocument('users', 'user-123', {
  age: 31,
  active: false,
  updatedAt: new Date().toISOString()
});

console.log('User updated');

await db.updateDocument('users', 'user-123', {
  'age': 31,
  'active': false,
});

print('User updated');

updates := map[string]interface{}{
    "age":    31,
    "active": false,
}

doc, err := client.UpdateDocument(ctx, "users", "user-123", updates)
if err != nil {
    log.Fatal(err)
}

fmt.Println("User updated")

db.update_document('users', 'user-123', {
    'age': 31,
    'active': False
})

print("User updated")

curl -X PATCH https://api.cocobase.buzz/collections/users/documents/user-123 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "age": 31,
    "active": false
  }'

Updates are partial by default - you only need to provide the fields you want to change. Other fields remain unchanged.

Batch Update

JavaScript
Dart
Go
Python
HTTP

await db.updateDocuments('users', {
  'user-1': { age: 31, updatedAt: new Date().toISOString() },
  'user-2': { age: 29, updatedAt: new Date().toISOString() },
  'user-3': { active: false, updatedAt: new Date().toISOString() }
});

// Update documents individually
final updates = {
  'user-1': {'age': 31},
  'user-2': {'age': 29},
  'user-3': {'active': false},
};

for (var entry in updates.entries) {
  await db.updateDocument('users', entry.key, entry.value);
}

// Update documents individually
updates := map[string]map[string]interface{}{
    "user-1": {"age": 31},
    "user-2": {"age": 29},
    "user-3": {"active": false},
}

for docID, data := range updates {
    _, err := client.UpdateDocument(ctx, "users", docID, data)
    if err != nil {
        log.Printf("Failed to update %s: %v\n", docID, err)
    }
}

# Update documents individually
updates = {
    'user-1': {'age': 31},
    'user-2': {'age': 29},
    'user-3': {'active': False}
}

for doc_id, data in updates.items():
    db.update_document('users', doc_id, data)

curl -X POST https://api.cocobase.buzz/collections/users/batch/documents/update \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": {
      "user-1": {"data": {"age": 31}},
      "user-2": {"data": {"age": 29}},
      "user-3": {"data": {"active": false}}
    }
  }'

Delete Documents

Remove documents from collections permanently.

Delete Single Document

JavaScript
Go
Python
HTTP

await db.deleteDocument('users', 'user-123');
console.log('User deleted');```
</Tab>

<Tab title="Dart">
```dart
await db.deleteDocument('users', 'user-123');
print('User deleted');

err := client.DeleteDocument(ctx, "users", "user-123")
if err != nil {
    log.Fatal(err)
}

fmt.Println("User deleted")

db.delete_document('users', 'user-123')
print("User deleted")

curl -X DELETE https://api.cocobase.buzz/collections/users/documents/user-123 \
  -H "X-API-Key: your-api-key"

Batch Delete

JavaScript
Dart
Go
Python
HTTP

const idsToDelete = ['user-1', 'user-2', 'user-3'];
const result = await db.deleteDocuments('users', idsToDelete);
console.log(`Deleted ${result.count} documents`);

final idsToDelete = ['user-1', 'user-2', 'user-3'];

for (var id in idsToDelete) {
  await db.deleteDocument('users', id);
}

print('Deleted ${idsToDelete.length} documents');

idsToDelete := []string{"user-1", "user-2", "user-3"}

for _, id := range idsToDelete {
    err := client.DeleteDocument(ctx, "users", id)
    if err != nil {
        log.Printf("Failed to delete %s: %v\n", id, err)
    }
}

ids_to_delete = ['user-1', 'user-2', 'user-3']

for doc_id in ids_to_delete:
    db.delete_document('users', doc_id)

print(f"Deleted {len(ids_to_delete)} documents")

curl -X POST https://api.cocobase.buzz/collections/users/batch/documents/delete \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "document_ids": ["user-1", "user-2", "user-3"]
  }'

Soft Delete (Recommended)

Instead of permanently deleting, mark documents as deleted for recovery options.

JavaScript
Go
Python
HTTP

// Mark as deleted instead of permanent removal
await db.updateDocument('users', 'user-123', {
  deleted: true,
  deletedAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
});

// Query non-deleted
const activeUsers = await db.listDocuments('users', {
  filters: { deleted: false }
});
``
</Tab>

<Tab title="Dart">
```dart
// Mark as deleted
await db.updateDocument('users', 'user-123', {
  'deleted': true,
  'deletedAt': DateTime.now().toIso8601String(),
});

// Query non-deleted items
final activeUsers = await db.listDocuments('users', filters: {
  'deleted': false,
});

// Mark as deleted
updates := map[string]interface{}{
    "deleted":   true,
    "deletedAt": time.Now().Format(time.RFC3339),
}

_, err := client.UpdateDocument(ctx, "users", "user-123", updates)

// Query non-deleted items
query := cocobase.NewQuery().Where("deleted", false)
activeUsers, err := client.ListDocuments(ctx, "users", query)

from datetime import datetime

# Mark as deleted
db.update_document('users', 'user-123', {
    'deleted': True,
    'deletedAt': datetime.utcnow().isoformat()
})

# Query non-deleted items
active_users = db.list_documents('users', filters={
    'deleted': False
})

# Mark as deleted
curl -X PATCH https://api.cocobase.buzz/collections/users/documents/user-123 \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "deleted": true,
    "deletedAt": "2024-01-15T10:30:00Z"
  }'

# Query non-deleted items
curl "https://api.cocobase.buzz/collections/users/documents?deleted=false" \
  -H "X-API-Key: your-api-key"

Error Handling

Handle errors gracefully across all operations.

JavaScript
Dart
Go
Python
HTTP

try {
  const user = await db.getDocument('users', 'user-123');
  console.log(user.data);
} catch (error) {
  // Cocobase error structure might include statusCode
  if (error?.statusCode === 404) {
    console.error('Document not found');
  } else if (error?.statusCode === 401) {
    console.error('Unauthorized: Invalid API key');
  } else if (error?.statusCode === 403) {
    console.error('Permission denied');
  } else {
    console.error('Unexpected error:', error.message || error);
  }
}

try {
  final user = await db.getDocument('users', userId);
  print(user);
} on DioException catch (e) {
  if (e.response?.statusCode == 404) {
    print('Document not found');
  } else {
    print('Network error: ${e.message}');
  }
} catch (e) {
  print('Unexpected error: $e');
}

doc, err := client.GetDocument(ctx, "users", userID)
if err != nil {
    if apiErr, ok := err.(*cocobase.APIError); ok {
        switch apiErr.StatusCode {
        case 404:
            fmt.Println("Document not found")
        case 401:
            fmt.Println("Not authenticated")
        case 403:
            fmt.Println("Permission denied")
        default:
            fmt.Printf("Error: %s\n", apiErr.Suggestion)
        }
    } else {
        log.Fatal(err)
    }
}

try:
    user = db.get_document('users', user_id)
    print(user)
except Exception as e:
    if '404' in str(e):
        print("Document not found")
    else:
        print(f"Failed to fetch user: {e}")

# Check HTTP status codes
# 200 OK - Success
# 404 Not Found - Document doesn't exist
# 401 Unauthorized - Invalid API key
# 403 Forbidden - Permission denied
# 500 Internal Server Error - Server error

Best Practices

1. Use Type Safety

Define your data structures for better development experience and fewer bugs.

// ✓ Good: Type-safe
interface User {
  name: string;
  email: string;
}

const user = await db.createDocument<User>('users', {
  name: 'John',
  email: 'john@example.com'
});

2. Handle Errors

Always wrap operations in try-catch blocks or check for errors.

// ✓ Good: Error handling
try {
  const user = await db.getDocument('users', userId);
  console.log(user);
} catch (error) {
  console.error('Failed to fetch user:', error.message);
}

3. Use Batch Operations

Batch operations are more efficient than multiple individual requests.

// ✓ Good: Single batch operation
await db.createDocuments('users', [user1, user2, user3]);

// ✗ Bad: Multiple individual operations
await db.createDocument('users', user1);
await db.createDocument('users', user2);
await db.createDocument('users', user3);

4. Prefer Soft Deletes

Use soft deletes for important data to enable recovery.

// ✓ Good: Soft delete
await db.updateDocument('users', userId, {
  deleted: true,
  deletedAt: new Date().toISOString()
});

5. Add Timestamps

Track when records are created and modified.

// ✓ Good: Include timestamps
const post = await db.createDocument('posts', {
  title: 'My Post',
  content: '...',
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString()
});

Getting Started

Core Concepts

Features

Cloud Functions

SDK Reference

Guides

CRUD Operations

CRUD Operations

Overview

Create Documents

Basic Creation

Type-Safe Creation

Batch Creation

Read Documents

Get Single Document

List All Documents

With Filters

Update Documents

Basic Update

Batch Update

Delete Documents

Delete Single Document

Batch Delete

Soft Delete (Recommended)

Error Handling

Best Practices

Next Steps

Query & Filtering

Relationships

Real-time Updates

File Storage

Getting Started

Core Concepts

Features

Cloud Functions

SDK Reference

Guides

​CRUD Operations

​Overview

​Create Documents

​Basic Creation

​Type-Safe Creation

​Batch Creation

​Read Documents

​Get Single Document

​List All Documents

​With Filters

​With Pagination

​Update Documents

​Basic Update

​Batch Update

​Delete Documents

​Delete Single Document

​Batch Delete

​Soft Delete (Recommended)

​Error Handling

​Best Practices

​Next Steps

Query & Filtering

Relationships

Real-time Updates

File Storage

CRUD Operations

Overview

Create Documents

Basic Creation

Type-Safe Creation

Batch Creation

Read Documents

Get Single Document

List All Documents

With Filters

With Pagination

Update Documents

Basic Update

Batch Update

Delete Documents

Delete Single Document

Batch Delete

Soft Delete (Recommended)

Error Handling

Best Practices

Next Steps