Data Operators

Data Operators allow you to transform and update data structures declaratively. They are used in write operations to modify field values during updates and inserts.

Operators Quick Reference

Basic Operations:

Operator	Description
$set	Set a value
$replace	Replace a value
$incr	Increment a numeric value
$decr	Decrement a numeric value

Date/Time Operations:

Operator	Description
$now	Set current datetime or shifted datetime
$datetime	Set current datetime or shifted datetime (alias to $now)
$timestamp	Set current timestamp

ID Generation:

Operator	Description
$uuid	Generate UUID (no dashes)
$uuid4	Generate UUID v4 (with dashes)
$uuid7	Generate UUID v7

Data Operations:

Operator	Description
$rename	Move/rename a value to a new path
$copy	Copy a value to a new path
$length	Set the length of another value

List Operations:

Operator	Description
$push	Push item to end of array
$lpush	Push item to front of array
$extend	Append multiple items to end
$lextend	Prepend multiple items to front
$addset	Add items uniquely (no duplicates)
$pop	Remove item from end
$lpop	Remove item from front
$remove	Remove matching items
$clear	Remove all items

---

Overview

Data Operators - Powerful operators for modifying data in place. Used to set values, increment numbers, manipulate arrays, generate IDs, and perform complex data transformations.

Where Data Operators are used:

• db.update - Update document fields
• db.upsert - Update or insert with transformations
• db.insert - Transform data on insert

Mutation structure:

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "name": "Jane Doe",
    "score:$incr": 10,
    "tags:$push": "premium",
    "updated_at:$now": true,
    "id:$uuid4": true
  }
}

---

Mutation Syntax

Data Operators use the :$ syntax in the field key:

{
  "field:$operator": value,
  "nested.path.field:$operator": value
}

Components:

• field - Property name to mutate (supports dot notation for nested fields)
• :$operator - The mutation operator
• value - Value for the mutation (some operators auto-generate values)

---

Basic Operations

$set - Set Value

Set a field to a specific value.

{
  "name:$set": "John Doe",
  "status:$set": "active"
}

Use cases:

• Update field values
• Set new fields
• Replace existing data

Example:

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "email:$set": "newemail@example.com",
    "verified:$set": true
  }
}

Note: For simple value updates, the :$set operator can be omitted:

{
  "email": "newemail@example.com",
  "verified": true
}

---

$replace - Replace Value

Replace a field value.

{
  "settings:$replace": { "theme": "dark", "notifications": true }
}

Use cases:

• Replace entire objects
• Overwrite complex structures
• Reset fields

Example:

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "preferences:$replace": {
      "language": "en",
      "timezone": "UTC"
    }
  }
}

---

$incr - Increment Value

Increment a numeric field by a specified amount.

{
  "score:$incr": 10,
  "views:$incr": 1
}

Use cases:

• Update counters
• Track metrics
• Increment scores

Example:

{
  "op": "db.update",
  "collection": "posts",
  "filter": { "_key": "post_123" },
  "data": {
    "views:$incr": 1,
    "likes:$incr": 1,
    "engagement_score:$incr": 0.5
  }
}

---

$decr - Decrement Value

Decrement a numeric field by a specified amount.

{
  "credits:$decr": 5,
  "stock:$decr": 1
}

Use cases:

• Reduce inventory
• Decrease counters
• Update balances

Example:

{
  "op": "db.update",
  "collection": "inventory",
  "filter": { "_key": "product_123" },
  "data": {
    "stock:$decr": 1,
    "reserved:$decr": 1
  }
}

---

Date/Time Operations

$now - Current Datetime

Set field to current datetime. Can optionally shift the time.

{
  "created_at:$now": true,
  "updated_at:$now": true
}

Use cases:

• Timestamp creation
• Update tracking
• Time-based events

Example:

{
  "op": "db.update",
  "collection": "documents",
  "filter": { "_key": "doc_123" },
  "data": {
    "last_modified:$now": true,
    "published_at:$now": true
  }
}

With time shift (if supported):

{
  "expires_at:$now": "+7d",
  "scheduled_for:$now": "+1h"
}

---

$datetime - Current Datetime (Alias)

Alias for $now. Sets field to current datetime.

{
  "timestamp:$datetime": true
}

Example:

{
  "op": "db.insert",
  "collection": "logs",
  "data": {
    "event": "user_login",
    "occurred_at:$datetime": true
  }
}

---

$timestamp - Current Timestamp

Set field to current Unix timestamp (seconds since epoch).

{
  "created:$timestamp": true
}

Use cases:

• Unix timestamp storage
• Numeric time comparisons
• Sorting by time

Example:

{
  "op": "db.update",
  "collection": "sessions",
  "filter": { "_key": "session_123" },
  "data": {
    "last_activity:$timestamp": true
  }
}

---

ID Generation

$uuid - Generate UUID (No Dashes)

Generate a UUID without dashes.

{
  "tracking_id:$uuid": true
}

Output format: 550e8400e29b41d4a716446655440000

Use cases:

• Compact IDs
• Tracking codes
• Reference numbers

Example:

{
  "op": "db.insert",
  "collection": "orders",
  "data": {
    "order_id:$uuid": true,
    "customer": "user_123"
  }
}

---

$uuid4 - Generate UUID v4 (With Dashes)

Generate a UUID v4 with dashes.

{
  "id:$uuid4": true
}

Output format: 550e8400-e29b-41d4-a716-446655440000

Use cases:

• Standard UUIDs
• External IDs
• API keys

Example:

{
  "op": "db.insert",
  "collection": "api_keys",
  "data": {
    "key:$uuid4": true,
    "user_id": "user_123",
    "created_at:$now": true
  }
}

---

$uuid7 - Generate UUID v7

Generate a UUID v7 (time-based).

{
  "id:$uuid7": true
}

Output format: Time-ordered UUID

Use cases:

• Sortable UUIDs
• Time-based IDs
• Distributed systems

Example:

{
  "op": "db.insert",
  "collection": "events",
  "data": {
    "event_id:$uuid7": true,
    "type": "page_view"
  }
}

---

Data Operations

$rename - Move/Rename Field

Move or rename a value to a new path.

{
  "old_field:$rename": "new_field"
}

Use cases:

• Restructure data
• Migrate field names
• Reorganize documents

Example:

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "username:$rename": "display_name",
    "user.email:$rename": "contact.primary_email"
  }
}

---

$copy - Copy Field

Copy a value to a new path.

{
  "source_field:$copy": "destination_field"
}

Use cases:

• Duplicate data
• Create backups
• Mirror values

Example:

{
  "op": "db.update",
  "collection": "products",
  "filter": { "_key": "prod_123" },
  "data": {
    "price:$copy": "original_price",
    "description:$copy": "description_backup"
  }
}

---

$length - Get Length

Set the length of another value (string, array, object).

{
  "tag_count:$length": "tags",
  "name_length:$length": "name"
}

Use cases:

• Count items
• Measure strings
• Track sizes

Example:

{
  "op": "db.update",
  "collection": "posts",
  "filter": { "_key": "post_123" },
  "data": {
    "tag_count:$length": "tags",
    "comment_count:$length": "comments"
  }
}

---

List Operations

$push - Add to End

Push a single item to the end of an array.

{
  "tags:$push": "featured",
  "history:$push": { "action": "updated", "timestamp": "2024-01-15" }
}

Use cases:

• Add tags
• Append logs
• Add items to lists

Example:

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "tags:$push": "premium",
    "login_history:$push": {
      "ip": "192.168.1.1",
      "timestamp:$now": true
    }
  }
}

Note: Can push scalar values, objects, or even arrays as a single element.

---

$lpush - Add to Front

Push a single item to the front of an array.

{
  "notifications:$lpush": { "type": "alert", "message": "New update" }
}

Use cases:

• Recent items first
• Priority queues
• Latest-first lists

Example:

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "notifications:$lpush": {
      "message": "New message received",
      "timestamp:$now": true
    }
  }
}

---

$extend - Append Multiple Items

Append multiple items (spread list) to the end of an array.

{
  "tags:$extend": ["sale", "featured", "popular"]
}

Use cases:

• Add multiple tags
• Merge lists
• Batch append

Example:

{
  "op": "db.update",
  "collection": "products",
  "filter": { "_key": "prod_123" },
  "data": {
    "tags:$extend": ["sale", "clearance", "limited-time"],
    "categories:$extend": ["electronics", "gadgets"]
  }
}

---

$lextend - Prepend Multiple Items

Prepend multiple items (spread list) to the front of an array.

{
  "history:$lextend": [
    { "action": "created" },
    { "action": "updated" }
  ]
}

Use cases:

• Latest items first
• Prepend batches
• Reverse chronological

Example:

{
  "op": "db.update",
  "collection": "feeds",
  "filter": { "_key": "feed_123" },
  "data": {
    "posts:$lextend": [
      { "id": "post_3", "created:$now": true },
      { "id": "post_2", "created:$now": true }
    ]
  }
}

---

$addset - Add Unique Items

Add one or more items uniquely (no duplicates) to an array.

{
  "tags:$addset": ["featured", "popular"]
}

Use cases:

• Unique tags
• Prevent duplicates
• Set operations

Example:

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "roles:$addset": ["editor", "contributor"],
    "permissions:$addset": ["read", "write"]
  }
}

Note: Only adds items that don't already exist in the array.

---

$pop - Remove from End

Remove one item from the end of an array.

{
  "history:$pop": true
}

Use cases:

• Remove last item
• Stack operations
• Limit array size

Example:

{
  "op": "db.update",
  "collection": "logs",
  "filter": { "_key": "log_123" },
  "data": {
    "events:$pop": true
  }
}

---

$lpop - Remove from Front

Remove one item from the front of an array.

{
  "queue:$lpop": true
}

Use cases:

• Queue operations
• Remove oldest item
• FIFO processing

Example:

{
  "op": "db.update",
  "collection": "queues",
  "filter": { "_key": "queue_123" },
  "data": {
    "pending_jobs:$lpop": true
  }
}

---

$remove - Remove Matching Items

Remove items that match a specific value.

{
  "tags:$remove": "draft",
  "roles:$remove": "viewer"
}

Use cases:

• Remove specific items
• Filter arrays
• Clean up lists

Example:

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "tags:$remove": "temporary",
    "permissions:$remove": "write"
  }
}

---

$clear - Remove All Items

Remove all items from an array.

{
  "tags:$clear": true,
  "history:$clear": true
}

Use cases:

• Reset arrays
• Clear all data
• Start fresh

Example:

{
  "op": "db.update",
  "collection": "carts",
  "filter": { "_key": "cart_123" },
  "data": {
    "items:$clear": true,
    "applied_coupons:$clear": true
  }
}

---

Usage in Operations

db.update - Update with Mutations

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "name": "Jane Doe",
    "score:$incr": 10,
    "tags:$push": "premium",
    "updated_at:$now": true
  }
}

db.upsert - Upsert with Mutations

{
  "op": "db.upsert",
  "collection": "settings",
  "filter": { "user_id": "user_123" },
  "update": {
    "theme": "dark",
    "last_updated:$now": true
  },
  "insert": {
    "user_id": "user_123",
    "theme": "light",
    "created_at:$now": true,
    "id:$uuid4": true
  }
}

db.insert - Insert with Auto-Generated Values

{
  "op": "db.insert",
  "collection": "orders",
  "data": {
    "order_id:$uuid4": true,
    "user_id": "user_123",
    "total": 99.99,
    "created_at:$now": true,
    "status": "pending"
  }
}

---

Combining Data Operators

You can use multiple Data Operators in a single update:

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "name": "Jane Doe",
    "score:$incr": 50,
    "level:$incr": 1,
    "achievements:$push": "first_win",
    "tags:$addset": ["active", "premium"],
    "last_login:$now": true,
    "session_id:$uuid4": true,
    "login_count:$incr": 1
  }
}

---

Common Patterns

User Activity Tracking

{
  "op": "db.update",
  "collection": "users",
  "filter": { "_key": "user_123" },
  "data": {
    "last_active:$now": true,
    "activity_count:$incr": 1,
    "recent_actions:$push": {
      "action": "login",
      "timestamp:$now": true
    }
  }
}

Order Creation

{
  "op": "db.insert",
  "collection": "orders",
  "data": {
    "order_id:$uuid4": true,
    "user_id": "user_123",
    "items": [
      { "product": "prod_1", "quantity": 2 }
    ],
    "total": 199.98,
    "status": "pending",
    "created_at:$now": true,
    "tracking_id:$uuid": true
  }
}

Inventory Management

{
  "op": "db.update",
  "collection": "products",
  "filter": { "_key": "prod_123" },
  "data": {
    "stock:$decr": 1,
    "sold_count:$incr": 1,
    "last_sold:$now": true,
    "purchase_history:$push": {
      "order_id": "order_456",
      "timestamp:$now": true
    }
  }
}

Tag Management

{
  "op": "db.update",
  "collection": "articles",
  "filter": { "_key": "article_123" },
  "data": {
    "tags:$addset": ["featured", "trending"],
    "published_tags:$remove": "draft",
    "tag_count:$length": "tags",
    "updated_at:$now": true
  }
}