Collections & Documents

Cocobase uses a document-based data model similar to MongoDB and Firestore. Data is organized into collections containing documents (JSON objects).

What is a Collection?

A collection is a group of related documents. Think of it like a table in a relational database, but without a fixed schema. Examples:

users - User profiles and account data
posts - Blog posts or social media content
products - E-commerce product catalog
orders - Customer orders

What is a Document?

A document is a JSON object containing your data. Each document has a specific structure:

id - Unique identifier (auto-generated)
collection - Name of the collection this document belongs to
createdAt - Creation timestamp (auto-generated)
updatedAt - Last update timestamp (auto-generated)
data - Object containing your custom fields

Document Structure:

{
  "id": "507f1f77bcf86cd799439011",
  "collection": "users",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "data": {
    "name": "Alice Johnson",
    "email": "alice@example.com",
    "age": 28,
    "role": "developer",
    "preferences": {
      "theme": "dark",
      "notifications": true
    },
    "tags": ["javascript", "react", "nodejs"]
  }
}

Important: All your custom fields are stored inside the data property. The top-level properties (id, collection, createdAt, updatedAt) are managed by Cocobase.

Schema-less Design

Collections in Cocobase are schema-less - documents in the same collection can have different fields.

JavaScript
Dart
Go
Python

// These can all exist in the same collection
await db.createDocument({
collection: "products",
data: {
type: "book",
title: "Learning TypeScript",
author: "John Doe",
pages: 350
}
});

await db.createDocument({
collection: "products",
data: {
type: "laptop",
brand: "Apple",
model: "MacBook Pro",
specs: {
  ram: "16GB",
  storage: "512GB"
}
}
});

// Different structures, same collection
await db.createDocument('products', {
  'type': 'book',
  'title': 'Learning TypeScript',
  'author': 'John Doe',
  'pages': 350,
});

await db.createDocument('products', {
  'type': 'laptop',
  'brand': 'Apple',
  'model': 'MacBook Pro',
  'specs': {
    'ram': '16GB',
    'storage': '512GB',
  },
});

// Flexible document structures
db.CreateDocument(ctx, "products", map[string]any{
    "type":   "book",
    "title":  "Learning TypeScript",
    "author": "John Doe",
    "pages":  350,
})

db.CreateDocument(ctx, "products", map[string]any{
    "type":  "laptop",
    "brand": "Apple",
    "model": "MacBook Pro",
    "specs": map[string]any{
        "ram":     "16GB",
        "storage": "512GB",
    },
})

# Schema-less flexibility
db.create_document("products", {
    "type": "book",
    "title": "Learning TypeScript",
    "author": "John Doe",
    "pages": 350
})

db.create_document("products", {
    "type": "laptop",
    "brand": "Apple",
    "model": "MacBook Pro",
    "specs": {
        "ram": "16GB",
        "storage": "512GB"
    }
})

Supported Data Types

Cocobase supports all JSON data types:

Type	Description	Example
String	Text data	`"Hello World"`
Number	Integers and floats	`42`, `3.14`
Boolean	True/false values	`true`, `false`
Array	Ordered lists	`[1, 2, 3]`, `["a", "b"]`
Object	Nested objects	`{ "name": "John" }`
Null	Null value	`null`
Date	ISO 8601 strings	`"2024-01-15T10:30:00Z"`

Nested Objects

You can nest objects as deeply as needed:

{
  "user": {
    "name": "Alice",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "geo": {
        "lat": 40.7128,
        "lng": -74.006
      }
    }
  }
}

Arrays

Arrays can contain any data type:

{
  "tags": ["javascript", "react", "nodejs"],
  "scores": [85, 92, 78],
  "metadata": [
    { "key": "category", "value": "tech" },
    { "key": "priority", "value": 1 }
  ]
}

Collection Naming

Best practices for naming collections:

Use lowercase - users, not Users
Use plural - posts, not post
Use underscores for multi-word - blog_posts
Keep names descriptive - product_reviews, not pr
Avoid special characters except _ and -

Good names:

users
blog_posts
product_reviews
order_items
user_preferences

Avoid:

User          // Not plural
blogPost      // Use snake_case
pr            // Too short
product$      // Special characters
123_test      // Starting with number

Document IDs

Every document has a unique id field:

Auto-generated
Custom ID

// Cocobase generates a unique ID
const doc = await db.createDocument({
collection: "users",
data: {
name: "Alice"
}
});

console.log(doc.id);

// Provide your own ID
const doc = await db.createDocument({
collection: "users",
id: "user_alice_2024",
data: {
name: "Alice"
}
});

console.log(doc.id);

Custom IDs must be unique within the collection. Attempting to create a document with an existing ID will fail.

Automatic Fields

Cocobase automatically adds these fields to every document:

`id` - Unique Identifier

{
  "id": "507f1f77bcf86cd799439011"
}

`createdAt` - Creation Timestamp

{
  "createdAt": "2024-01-15T10:30:00Z"
}

`updatedAt` - Last Update Timestamp

{
  "updatedAt": "2024-01-15T15:45:00Z"
}

These fields are managed automatically. You cannot override them when creating or updating documents.

Collection Operations

Create a Collection

Collections are created automatically when you insert the first document:

JavaScript
Dart
Go
Python

// Collection "users" is created automatically
await db.createDocument({
collection: "users",
data: {
name: "Alice"
}
});

// Collection is created on first insert
await db.createDocument('users', {
  'name': 'Alice',
});

// Auto-creates collection
db.CreateDocument(ctx, "users", map[string]any{
    "name": "Alice",
})

# Collection created automatically
db.create_document("users", {
    "name": "Alice"
})

List Collections

JavaScript
Dart
Go
Python

const collections = await db.listCollections();
console.log(collections); // ["users", "posts", "products"]

final collections = await db.listCollections();
print(collections); // ["users", "posts", "products"]

collections, err := db.ListCollections(ctx)
if err != nil {
    log.Fatal(err)
}
// collections: ["users", "posts", "products"]

collections = db.list_collections()
print(collections)  # ["users", "posts", "products"]

Delete a Collection

Deleting a collection permanently removes all documents. This action cannot be undone.

JavaScript
Dart
Go
Python

await db.deleteCollection("old_data");

await db.deleteCollection('old_data');

err := db.DeleteCollection(ctx, "old_data")
if err != nil {
    log.Fatal(err)
}

db.delete_collection("old_data")

Document Size Limits

Maximum document size: 16 MB
Maximum nesting depth: 100 levels
Maximum array length: 100,000 elements

For large files (images, videos, documents), use File Storage instead of embedding in documents.

Best Practices

Keep Documents Focused

Each document should represent a single entity. Don’t try to store your entire application state in one document.

// ✅ Good - Focused document
{
  "id": "user_123",
  "name": "Alice",
  "email": "alice@example.com"
}

// ❌ Bad - Too much data
{
  "id": "user_123",
  "name": "Alice",
  "posts": [...100 posts...],
  "comments": [...500 comments...],
  "friends": [...200 friends...]
}

Instead of embedding everything, use document references and population.

// ✅ Good - Use references
{
  "id": "post_456",
  "title": "My Post",
  "authorId": "user_123"  // Reference to user
}

// Then populate when needed
const posts = await db.listDocuments({
collection: "posts",
populate: ["authorId"]
});

Index Frequently Queried Fields

Add indexes for fields you query often to improve performance.

// Create index on email field
await db.createIndex({
collection: "users",
field: "email"
});

// Queries on email will be faster
const user = await db.listDocuments({
collection: "users",
filters: {
email: { $eq: "alice@example.com" }
}
});

Use Consistent Field Names

Stick to a naming convention across your application.

// ✅ Good - Consistent naming
{
  "userId": "user_123",
  "createdBy": "user_456",
  "assignedTo": "user_789"
}

// ❌ Bad - Inconsistent
{
  "userId": "user_123",
  "creator": "user_456",
  "assigned_user_id": "user_789"
}

Type Safety (TypeScript)

Use TypeScript interfaces for type-safe operations:

interface User {
  id: string;
  name: string;
  email: string;
  age?: number;
  role: "admin" | "user" | "moderator";
  createdAt: string;
  updatedAt: string;
}

const user = await db.createDocument<User>({
  collection: "users",
  data: {
    name: "Alice",
    email: "alice@example.com",
    role: "user"
  }
});
// user is typed as User
console.log(user.name); // ✅ TypeScript knows this exists
console.log(user.foo); // ❌ TypeScript error

Next Steps

CRUD Operations

Learn to create, read, update, and delete documents

Querying Data

Master filtering and searching your collections

Relationships

Connect documents with references

Data Types

Deep dive into supported data types

Getting Started

Core Concepts

Data & Querying

Cloud Functions

Hooks

Realtime & Multiplayer

Storage

Auth & Security

Guides

SDK Reference

API Reference

Collections & Documents

Collections & Documents

What is a Collection?

What is a Document?

Schema-less Design

Supported Data Types

Nested Objects

Arrays

Collection Naming

Document IDs

Automatic Fields

`id` - Unique Identifier

`createdAt` - Creation Timestamp

`updatedAt` - Last Update Timestamp

Collection Operations

Create a Collection

List Collections

Delete a Collection

Document Size Limits

Best Practices

Type Safety (TypeScript)

Next Steps

CRUD Operations

Querying Data

Relationships

Data Types

​Collections & Documents

​What is a Collection?

​What is a Document?

​Schema-less Design

​Supported Data Types

​Nested Objects

​Arrays

​Collection Naming

​Document IDs

​Automatic Fields

​id - Unique Identifier

​createdAt - Creation Timestamp

​updatedAt - Last Update Timestamp

​Collection Operations

​Create a Collection

​List Collections

​Delete a Collection

​Document Size Limits

​Best Practices

​Type Safety (TypeScript)

​Next Steps

CRUD Operations

Querying Data

Relationships

Data Types

Collections & Documents

What is a Collection?

What is a Document?

Schema-less Design

Supported Data Types

Nested Objects

Arrays

Collection Naming

Document IDs

Automatic Fields

`id` - Unique Identifier

`createdAt` - Creation Timestamp

`updatedAt` - Last Update Timestamp

Collection Operations

Create a Collection

List Collections

Delete a Collection

Document Size Limits

Best Practices

Type Safety (TypeScript)

Next Steps