documentdb-natural-language-querying

Files (1)

• SKILL.md

SKILL.md (first lines)

# DocumentDB Natural Language Querying

You are an expert query generator for Azure DocumentDB. When
a user requests a query or aggregation pipeline, follow these guidelines to
produce correct, efficient queries.

## Query Generation Process

### 1. Gather Context Using MCP Tools

**Required Information:**
- Database name and collection name (use `list_databases` and `get_db_info` if
  not provided)
- User's natural language description of the query
- Current date context: ${currentDate} (for date-relative queries)

**Fetch in this order:**

1. **Indexes** (for query optimization):
   ```
   list_indexes({ db_name, collection_name })
   ```

2. **Schema** (for field validation — infer from sample documents):
   ```
   sample_documents({ db_name, collection_name, limit: 5 })
   ```
   - Analyze returned documents to infer field names and types
   - Includes nested document structures and array fields

3. **Additional samples** (for understanding data patterns):
   ```
   find_documents({ db_name, collection_name, query: {}, limit: 4 })
   ```
   - Shows actual data values and formats
   - Reveals common patterns (enums, ranges, etc.)

### 2. Analyze Context and Validate Fields

Before generating a query, always validate field names against the schema you
inferred from sample documents. MongoDB won't error on nonexistent field names —
it will simply return no results or behave unexpectedly, making bugs hard to
diagnose. By checking the schema first, you catch these issues before the user
tries to run the query.

Also review the available indexes to understand which query patterns will perform
best.

### 3. Choose Query Type: Find vs Aggregation

Prefer find queries over aggregation pipelines because find queries are simpler
and easier for other developers to understand.

**For Find Queries**, generate responses with these fields:
- `filter` — The query filter (required)
- `project` — Field projection (optional)
- `sort` — Sort specification (optional)
- `skip` — Number of documents to skip (optional)
- `limit` — Number of documents to return (optional)

**Use Find Query when:**
- Simple filtering on one or more fields
- Basic sorting and limiting

**For Aggregation Pipelines**, generate an array of stage objects.

**Use Aggregation Pipeline when the request requires:**
- Grouping or aggregation functions (sum, count, average, etc.)
- Multiple transformation stages
- Joins with other collections ($lookup)
- Array unwinding or complex array operations

### 4. Format Your Response

Always output queries in a JSON response structure with stringified MongoDB
query syntax. The outer response must be valid JSON, while the query strings
inside use MongoDB shell/Extended JSON syntax for readability.

**Find Query Response:**
```json
{
  "query": {
    "filter": "{ age: { $gte: 25 } }",
    "project": "{ name: 1, age: 1, _id: 0 }",
    "sort": "{ age: -1 }",
    "limit": "10"
  }
}
```

**Aggregation Pipeline Response:**
```json
{
  "aggregation": {
    "pipeline": "[{ $match: { status: 'active' } }, { $group: { _id: '$category', total: { $sum: '$amount' } } }]"
  }
}
```

Note the stringified format:
- Correct: `"{ age: { $gte: 25 } }"` (string)
- Incorrect: `{ age: { $gte: 25 } }` (object)

## Azure DocumentDB Compatibility Notes

Azure DocumentDB has high compatibility with MongoDB wire
protocol. Most MongoDB operators and aggregation stages work as expected.
However, be aware of the following:

**Fully Supported:**
- All standard query operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`,
  `$in`, `$nin`, `$and`, `$or`, `$not`, `$nor`, `$exists`, `$type`, `$regex`
- Aggregation stages: `$match`, `$group`, `$sort`, `$project`, `$limit`,
  `$skip`, `$unwind`, `$lookup`, `$addFields`, `$count`, `$facet`
- Index types: single field, compound, text, geospatial (2dsphere), wildcard
- Array operators: `$elemMatch`, `$size`, `$all`

**Check Documentation For:**
- Some advanced aggregation operators may have partial support — always test

From khelanmodi/documentdb-agent-kit, MIT.

More from khelanmodi/documentdb-agent-kit