Index of every page on this site: llms.txt
All skills
microsoft avatar

/cosmosdb-mongodb

@e4b5866
by microsoftmicrosoft/scope89 stars
32
Run it yourself

Best practices for Azure Cosmos DB for MongoDB (RU-based). Use this skill when: (1) creating or modifying database indexes, (2) writing database migrations, (3) designing queries against CosmosDB, (4) troubleshooting query performance or index errors.

  • 1 file
  • 4.3 KB
  • Updated 6 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/microsoft/scope/cosmosdb-mongodb

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈67 tokens for metadata: the name and description. ≈1k when used: this file.

Description uses 3.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈270 characters, or 3.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Azure Cosmos DB for MongoDB (RU-based) Best Practices

Indexing Strategy

Prefer Single-Field Indexes for Equality Filters

Cosmos DB uses index intersection for multi-property equality filters. Create single-field indexes on each filtered field rather than large compound indexes:

// ✅ GOOD — single-field indexes, Cosmos intersects them for queries with multiple filters
await col.createIndex({ "run.status": 1 });
await col.createIndex({ workerType: 1 });
await col.createIndex({ deletedAt: 1 });

// ❌ BAD — large compound index may be silently ignored by Cosmos DB
await col.createIndex({ "run.status": 1, workerType: 1, deletedAt: 1, priority: -1, createdAt: 1 });

Use 2-Field Compound Indexes for ORDER BY

Cosmos DB requires a compound index that matches the sort fields. Keep it to 2 fields maximum for reliability:

// ✅ GOOD — 2-field compound for sort, single-field indexes handle the WHERE clause
await col.createIndex({ priority: -1, createdAt: 1 });

// ✅ GOOD — selective filter + sort field compound
await col.createIndex({ "run.postProcessorStatus": 1, updatedAt: -1 });

Large Compound Indexes May Be Silently Dropped

Cosmos DB (RU-based) silently drops compound indexes it cannot support — createIndex() succeeds but the index is never created. This leads to runtime errors like:

"The order by query does not have a corresponding composite index that it can be served from."

Always verify that your index was actually created:

db.collection.getIndexes()

Index Pattern for Polling Queries

For queries that combine equality filters with a sort (e.g., scheduler dispatchers), use this pattern:

  1. Single-field indexes on each equality filter field (from migration 009)
  2. A focused 2-field compound index: { mostSelectiveFilterField: 1, sortField: -1 }

Migration Best Practices

Structure

Migrations live in packages/db-migrations/src/migrations/ and implement MigrationInterface from mongo-migrate-ts:

import type { Db } from "mongodb";
import type { MigrationInterface } from "mongo-migrate-ts";

export class MyMigration implements MigrationInterface {
  async up(db: Db): Promise<void> { /* ... */ }
  async down(db: Db): Promise<void> { /* ... */ }
}

Always Wrap Index Operations in try/catch

Index creation or deletion may fail if the index already exists or doesn't exist. Never let this crash the migration:

try {
  await col.createIndex({ field: 1 });
  console.log("[NNN] Created index on field");
} catch (err: any) {
  console.log(`[NNN] Index already exists or couldn't be created: ${err.message ?? err}`);
}

Register in required-migrations.ts

Every new migration must be added to packages/db-migrations/src/required-migrations.ts. The API readiness probe checks that all required migrations have been applied.

down() Should Be Safe but Not Destructive

Dropping indexes in down() can be destructive in production. Prefer a log-only approach:

async down(db: Db): Promise<void> {
  console.log("[NNN-down] Skipping index drop — indexes should be dropped manually if needed");
}

Features NOT Supported or Limited

These MongoDB features do not work reliably in Cosmos DB for MongoDB (RU-based):

Feature Status
Large compound indexes (5+ fields) May be silently ignored
$text / text indexes Not supported
Certain aggregation stages Partial support — test each one
Change streams (resume after) Limited compared to native MongoDB
Transactions (multi-document) Supported only on API version 4.0+ with limitations

RU Cost Awareness

  • Every index increases write RU cost (each insert/update/delete must update all indexes)
  • Keep the total number of indexes reasonable — add indexes only for queries that actually run
  • Compound indexes cost more RUs per write than single-field indexes

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at e4b5866. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 6 months ago
metadata
{
  "version": "1.0.0"
}

README badge

README badge for microsoft/scope/cosmosdb-mongodb