> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cocobase.cc/llms.txt
> Use this file to discover all available pages before exploring further.
# Collections & Documents
> Understanding data organization in Cocobase
# 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:**
```json theme={null}
{
"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.
```typescript theme={null}
// 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"
}
}
});
```
```dart theme={null}
// 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',
},
});
```
```go theme={null}
// 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",
},
})
```
```python theme={null}
# 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:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```typescript theme={null}
// Cocobase generates a unique ID
const doc = await db.createDocument({
collection: "users",
data: {
name: "Alice"
}
});
console.log(doc.id);
```
```typescript theme={null}
// 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
```json theme={null}
{
"id": "507f1f77bcf86cd799439011"
}
```
### `createdAt` - Creation Timestamp
```json theme={null}
{
"createdAt": "2024-01-15T10:30:00Z"
}
```
### `updatedAt` - Last Update Timestamp
```json theme={null}
{
"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:
```typescript theme={null}
// Collection "users" is created automatically
await db.createDocument({
collection: "users",
data: {
name: "Alice"
}
});
```
```dart theme={null}
// Collection is created on first insert
await db.createDocument('users', {
'name': 'Alice',
});
```
```go theme={null}
// Auto-creates collection
db.CreateDocument(ctx, "users", map[string]any{
"name": "Alice",
})
```
```python theme={null}
# Collection created automatically
db.create_document("users", {
"name": "Alice"
})
```
### List Collections
```typescript theme={null}
const collections = await db.listCollections();
console.log(collections); // ["users", "posts", "products"]
```
```dart theme={null}
final collections = await db.listCollections();
print(collections); // ["users", "posts", "products"]
```
```go theme={null}
collections, err := db.ListCollections(ctx)
if err != nil {
log.Fatal(err)
}
// collections: ["users", "posts", "products"]
```
```python theme={null}
collections = db.list_collections()
print(collections) # ["users", "posts", "products"]
```
### Delete a Collection
Deleting a collection permanently removes all documents. This action cannot be
undone.
```typescript theme={null}
await db.deleteCollection("old_data");
```
```dart theme={null}
await db.deleteCollection('old_data');
```
```go theme={null}
err := db.DeleteCollection(ctx, "old_data")
if err != nil {
log.Fatal(err)
}
```
```python theme={null}
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](/features/file-storage) instead of embedding in documents.
## Best Practices
Each document should represent a single entity. Don't try to store your entire application state in one document.
```typescript theme={null}
// ✅ 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.
```typescript theme={null}
// ✅ 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"]
});
```
Add indexes for fields you query often to improve performance.
```typescript theme={null}
// 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" }
}
});
```
Stick to a naming convention across your application.
```typescript theme={null}
// ✅ 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:
```typescript theme={null}
interface User {
id: string;
name: string;
email: string;
age?: number;
role: "admin" | "user" | "moderator";
createdAt: string;
updatedAt: string;
}
const user = await db.createDocument({
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
Learn to create, read, update, and delete documents
Master filtering and searching your collections
Connect documents with references
Deep dive into supported data types