CRUD Operations

CosmosQL provides a complete set of CRUD (Create, Read, Update, Delete) operations with full type safety. This page provides an overview of all operations.

Create Operations

• Creating Documents - Create single and multiple documents
• create() - Create a single document
• createMany() - Create multiple documents in one operation

Read Operations

• Reading Documents - Query and retrieve documents
• findUnique() - Get a single document by ID + partition key (fastest: 1 RU)
• findMany() - Query multiple documents with filtering, sorting, and pagination
• query() - Execute raw SQL queries for advanced use cases

Update Operations

• Updating Documents - Modify existing documents
• update() - Update a single document
• updateMany() - Update multiple documents matching criteria
• upsert() - Update if exists, create if doesn't

Delete Operations

• Deleting Documents - Remove documents
• delete() - Delete a single document
• deleteMany() - Delete multiple documents matching criteria

Common Patterns

All operations follow consistent patterns:

Partition Key Requirement

Most operations require a partition key to ensure efficient queries:

// ✅ Good: Partition-scoped operation
const user = await db.users.findUnique({
  where: {
    id: 'user_123',
    email: 'john@example.com' // Partition key required
  }
});

// ⚠️ Expensive: Cross-partition (must explicitly opt-in)
const users = await db.users.findMany({
  enableCrossPartitionQuery: true,
  where: { isActive: true }
});

Type Safety

All operations are fully typed:

// TypeScript knows the exact return type
const user = await db.users.create({
  data: {
    id: 'user_123',
    email: 'john@example.com',
    name: 'John Doe',
    age: 30
  }
});
// user is typed as: { id: string; email: string; name: string; age: number; ... }

Error Handling

All operations can throw CosmosError:

import { isCosmosError } from 'cosmosql';

try {
  await db.users.create({ data: user });
} catch (error) {
  if (isCosmosError(error)) {
    // Handle CosmosDB-specific errors
    if (error.statusCode === 409) {
      // Duplicate ID
    }
  }
}

See Error Handling for complete error handling guide.

Next Steps

• Learn about Creating Documents
• Learn about Reading Documents
• Learn about Updating Documents
• Learn about Deleting Documents