Limitations

CosmosQL focuses on core CRUD operations and common query patterns that cover the majority of application use cases. This document outlines what's currently supported, what's missing, and workarounds for common scenarios.

Current Version Status

Production Ready: ✅ Yes - Core operations are stable and well-tested

Test Coverage: Comprehensive test suite covering all core functionality

Architecture:

• Zero dependencies - Only TypeScript required
• Type-level programming - Schema inference and type safety
• REST API direct - No SDK wrapper, minimal overhead
• Bun runtime - Optimized for Bun 1.0+ and Node.js 18+

Missing Features

1. Advanced Pagination

CosmosQL currently only supports offset-based pagination using take and skip. Cursor-based pagination and continuation tokens are not yet supported.

Current Support:

// Offset pagination (LIMIT/OFFSET)
const page1 = await db.posts.findMany({
  partitionKey: 'user_123',
  take: 20,
  skip: 0
});

const page2 = await db.posts.findMany({
  partitionKey: 'user_123',
  take: 20,
  skip: 20
});

Limitations:

• No cursor-based pagination
• No continuation token support
• Cross-partition queries with large offsets can be expensive

Workaround: For large datasets, consider:

1. Partition-scoped queries - Stay within partitions to minimize costs
2. Date/time-based filtering - Use timestamp filters instead of large offsets
3. Manual continuation tokens - Use raw SQL queries with continuation tokens (advanced)

Future Plans: Cursor-based pagination and continuation token support are planned.

2. Transaction Support

CosmosQL does not support:

• Multi-document transactions
• Batch operations beyond createMany (which requires same partition key)
• Transaction rollback capabilities
• Cross-partition transactions

Current Support:

// Single-partition batch operations only
await db.posts.createMany({
  data: [
    { id: 'post_1', userId: 'user_123', title: 'Post 1' },
    { id: 'post_2', userId: 'user_123', title: 'Post 2' }
  ],
  partitionKey: 'user_123' // All documents must share partition key
});

Limitations:

• Cannot atomically update multiple documents across partitions
• No rollback support
• Limited to operations within a single partition

Workaround: For multi-document operations:

1. Design for single-partition operations - Structure data so related documents share partition keys
2. Use application-level transactions - Implement compensating actions for failures
3. Use Azure SDK for transactions - For complex scenarios, use the official SDK alongside CosmosQL

Future Plans: Transaction support is under consideration for future releases.

3. Cross-Partition Query Limitations

Azure CosmosDB Restriction: Cross-partition queries are limited on empty containers. This is a CosmosDB limitation, not a CosmosQL limitation.

When attempting cross-partition queries on empty containers, CosmosDB returns an error. This is by design to prevent expensive operations on empty data.

Workaround: Ensure containers have at least one document before running cross-partition queries, or use partition-scoped queries when possible.

4. Advanced Query Features

The following CosmosDB features are not yet supported:

• Geospatial queries - Spatial indexing is supported in schema definition but full geospatial queries require raw SQL
• Full-text search - Integration with Azure Cognitive Search (not supported via REST API)
• JOIN operations - Not applicable to document databases, but no support for array joins
• Stored procedures - Cannot execute stored procedures (REST API focus)
• User-defined functions (UDFs) - Cannot use UDFs in queries (REST API focus)

Workaround: Use raw SQL queries for features not supported by the query builder:

// Geospatial example (when supported via raw SQL)
const result = await db.locations.query({
  sql: `
    SELECT * FROM c 
    WHERE ST_DISTANCE(c.location, {
      'type': 'Point',
      'coordinates': [@lng, @lat]
    }) < @distance
  `,
  parameters: [
    { name: '@lng', value: -122.4194 },
    { name: '@lat', value: 37.7749 },
    { name: '@distance', value: 5000 }
  ]
});

Future Plans: Advanced query features may be added based on community demand.

5. Performance Optimizations

Missing performance-related features:

• Query result caching - No built-in caching layer
• Query plan analysis - No automatic query optimization suggestions
• Automatic indexing suggestions - No recommendations for index optimization
• Connection pool management - Basic pooling exists, but limited configuration

Workaround:

1. Implement caching at application level - Use Redis or in-memory caching for frequently accessed data
2. Monitor RU usage - Track Request Unit consumption in Azure Portal
3. Optimize partition keys - Ensure good partition key selection (documented in Performance Guide)
4. Use point reads - Prefer findUnique over findMany when querying single documents

Future Plans: Performance monitoring and optimization tools may be added.

6. Change Feed

CosmosQL does not support:

• Change feed processors
• Real-time change notifications
• Document change tracking

Workaround: Use the official Azure SDK for change feed processing:

// Using Azure SDK for change feed
import { CosmosClient } from '@azure/cosmos';

const client = new CosmosClient(connectionString);
const container = client.database('mydb').container('users');

// Use SDK for change feed
const changeFeedProcessor = container.items
  .changeFeed({
    startFromBeginning: false
  })
  .on('change', (changes) => {
    // Handle changes
  });

Future Plans: Change feed support is being considered for future releases.

7. Multi-Database Operations

CosmosQL works with a single database per client instance. Cross-database operations are not supported.

Workaround: Create multiple client instances:

const productionDb = await createClient({
  connectionString: process.env.COSMOS_CONNECTION_STRING!,
  database: 'production',
  mode: 'verify'
}).withContainers({ users, posts });

const analyticsDb = await createClient({
  connectionString: process.env.COSMOS_CONNECTION_STRING!,
  database: 'analytics',
  mode: 'verify'
}).withContainers({ events, metrics });

Feature Comparison

When to Use CosmosQL vs Azure SDK

Use CosmosQL when:

• ✅ You prioritize type safety and developer experience
• ✅ You need zero dependencies for serverless/microservices
• ✅ Your use cases fit core CRUD operations
• ✅ You want compile-time guarantees for partition keys
• ✅ You're building new TypeScript applications
• ✅ You need database and container management (with auto-create, verify, or skip modes)

Use Azure SDK when:

• ✅ You need advanced features (change feed, stored procedures)
• ✅ You need cross-partition transactions
• ✅ You're working with JavaScript (not TypeScript)
• ✅ You need geospatial queries or full-text search

Use Both:

You can use CosmosQL alongside the Azure SDK for different use cases within the same project. They don't interfere with each other and work with the same database.

Roadmap

High Priority:

1. ✅ Core CRUD operations (Completed)
2. ✅ Type-safe query builder (Completed)
3. ✅ Aggregation functions (Completed)
4. 🔄 Cursor pagination (Planned)
5. 🔄 Batch operations (Planned)

Medium Priority:

1. ✅ Container management APIs (Completed)
2. ⏳ Advanced querying (Geospatial, full-text) (Future)
3. ⏳ Performance monitoring (Future)
4. ⏳ Migration support (Future)

Lower Priority:

1. ⏳ Multiple database support (Future)
2. ⏳ Advanced connection pooling (Future)
3. ⏳ Circuit breaker patterns (Future)

Reporting Issues

If you encounter limitations that impact your use case:

1. Check existing issues on GitHub
2. Create a feature request with use case details
3. Contribute - Pull requests welcome!
4. Use workarounds - Many limitations have documented workarounds

Getting Help

For questions about limitations or missing features:

• Check the FAQ for common questions
• Review Patterns & Use Cases for workarounds
• Open a GitHub issue for specific feature requests
• Join the community Discord for discussions