Cosmos DB API Selection Guide

Introduction

Azure Cosmos DB is a globally distributed, multi-model database service. Unlike traditional databases that force you into a single data model, Cosmos DB offers multiple APIs to interact with your data. This "multi-model" capability is one of its greatest strengths—and its greatest point of confusion for architects.

Choosing the right API is the most critical decision in your design phase. Once you commit to an API, migrating your data model to a different one later can be expensive and complex. This guide will help you navigate these options based on your application's data structure, query patterns, and existing ecosystem.

---

Understanding the API Options

Cosmos DB supports five primary APIs. Each is designed to handle specific data structures and developer workflows:

1. Core (SQL) API

The Core API is the native interface for Cosmos DB. It uses JSON as the storage format and SQL-like syntax for querying.

• Best for: General-purpose applications, microservices, and scenarios requiring high-performance document storage.
• Example: Storing user profiles, e-commerce product catalogs, or IoT sensor telemetry.

2. MongoDB API

This API provides wire-protocol compatibility with MongoDB. If you have an existing MongoDB application, you can migrate to Cosmos DB with minimal code changes.

• Best for: Migrating existing MongoDB workloads or teams already familiar with the MongoDB driver ecosystem.

3. Cassandra API

This API provides compatibility with Apache Cassandra. It is designed for wide-column stores.

• Best for: Time-series data, heavy write-throughput applications, and scenarios where you are already using Cassandra.

4. Gremlin (Graph) API

Designed for highly connected data, this API uses Apache TinkerPop to traverse relationships.

• Best for: Social networks, recommendation engines, and fraud detection systems where the relationship between entities is as important as the entities themselves.

5. Table API

A key-value store designed for simple, fast lookups.

• Best for: Simple data structures that do not require complex indexing or querying. It is the most cost-effective option for basic storage.

---

Practical Examples & Code Snippets

Scenario: Storing User Metadata (Core SQL API)

If you are building a modern web application, the Core API is usually the standard choice due to its rich indexing capabilities.

// Example: Creating a document in Core (SQL) API using Node.js SDK
const { CosmosClient } = require("@azure/cosmos");

const client = new CosmosClient({ endpoint, key });
const { database } = await client.databases.createIfNotExists({ id: "UserDB" });
const { container } = await database.containers.createIfNotExists({ id: "Profiles" });

const newUser = {
    id: "user_123",
    name: "Jane Doe",
    email: "[email protected]",
    preferences: { theme: "dark", notifications: true }
};

await container.items.create(newUser);

Scenario: Social Network Relationships (Gremlin API)

If you need to find "friends of friends," a graph structure is superior to a document structure.

// Example: Gremlin query to find friends of a user
g.V().has('user', 'name', 'Jane').out('follows').out('follows').dedup()

---

Best Practices for API Selection

1. Prioritize the Core (SQL) API: Unless you have a strict requirement for legacy compatibility (like existing Mongo drivers or Cassandra expertise), start with the Core API. It offers the most features, the best integration with Azure services (like Azure Functions and Synapse Link), and the best performance tuning options.
2. Evaluate Query Patterns First: Don't choose an API based on what you know; choose based on how you need to query. If your data is highly relational, don't force it into the Table API.
3. Use the Right Tool for Scaling: If you have massive write-heavy workloads, the Cassandra API excels at write-throughput. If you have complex, read-heavy analytical needs, the Core API's indexing policies are more robust.
4. Leverage Azure Synapse Link: If you choose the Core (SQL) API or MongoDB API, you can enable Synapse Link to perform near real-time analytics on your data without impacting transactional performance.

---

Common Pitfalls

• "The Migrator's Trap": Choosing an API just because you have existing code, even if that code's data model is a poor fit for the long-term requirements of the application. Always evaluate if a refactor to the Core API is worth the effort for better performance and feature access.
• Ignoring Partition Keys: Regardless of the API chosen, the Partition Key is the most important design element. Choosing a poor partition key will lead to "hot partitions," causing performance bottlenecks that no API change can fix.
• Over-indexing: While the Core API allows for powerful indexing, indexing every field increases your Request Unit (RU) consumption on every write. Only index the fields you actually query.

💡 Pro Tip: When in doubt, prototype.

Cosmos DB allows you to create multiple containers under the same account. You can prototype a small subset of your data in both the Core API and the API you are considering to compare the performance and the developer experience of the SDKs.

---

Key Takeaways

• Multi-Model Flexibility: Cosmos DB allows you to pick the API that fits your data model, not the other way around.
• Core API is the Default: For new greenfield projects, the Core (SQL) API is almost always the recommended path due to its maturity and feature set.
• Compatibility APIs: Use MongoDB, Cassandra, Gremlin, or Table APIs primarily for migrating existing applications or when team expertise is heavily tied to those specific ecosystems.
• Design for Scale: Regardless of the API, your success depends on choosing an effective Partition Key and optimizing your indexing policy.
• Future-Proofing: Consider how your data needs will evolve. If your data structure might become highly complex or deeply connected, choose an API that can handle that evolution gracefully.