Document Databases: The Schema-Flexible NoSQL Paradigm

The power of a database is measured not just by how it stores data, but by how expressively and efficiently you can retrieve it. Document databases offer a query language that feels natural to developers—working with JSON-like objects rather than SQL strings.

MongoDB's query language has evolved into a rich system of operators, modifiers, and patterns that can handle everything from simple lookups to complex analytical queries. Mastering this query language is essential for building performant applications.

In this page, we explore the full spectrum of MongoDB query capabilities—from fundamental CRUD operations through advanced text search and geospatial queries.

MongoDB queries use a filter document to specify matching criteria. The filter is a BSON object where keys are field names and values are matching conditions.

Find Operations

Find One Document:

// Find a single document by exact match
const user = await db.users.findOne({ email: "alice@example.com" });

// Find by ObjectId
const order = await db.orders.findOne({ 
  _id: ObjectId("507f1f77bcf86cd799439011") 
});

Find Multiple Documents:

// Find all matching documents
const activeUsers = await db.users.find({ status: "active" }).toArray();

// With chained modifiers
const recentOrders = await db.orders
  .find({ status: "pending" })
  .sort({ createdAt: -1 })
  .limit(10)
  .toArray();

CRUD Operations Overview

Update Operations

Update Operators:

// $set: Set field values
await db.users.updateOne(
  { _id: userId },
  { $set: { "profile.bio": "New bio", lastModified: new Date() } }
);

// $inc: Increment numeric fields
await db.products.updateOne(
  { _id: productId },
  { $inc: { viewCount: 1, stock: -1 } }
);

// $push: Add to array
await db.users.updateOne(
  { _id: userId },
  { $push: { tags: "premium" } }
);

// $addToSet: Add to array only if not present
await db.users.updateOne(
  { _id: userId },
  { $addToSet: { roles: "editor" } }
);

// $pull: Remove from array
await db.users.updateOne(
  { _id: userId },
  { $pull: { tags: "trial" } }
);

// $unset: Remove field
await db.users.updateOne(
  { _id: userId },
  { $unset: { temporaryFlag: "" } }
);

Comparison operators enable queries beyond simple equality matching.

Comparison Operator Reference

Examples

// Greater than / less than (range queries)
db.products.find({ 
  price: { $gte: 100, $lte: 500 } 
});

// Not equal
db.users.find({ status: { $ne: "banned" } });

// In a set of values
db.orders.find({ 
  status: { $in: ["pending", "processing", "shipped"] } 
});

// Not in a set
db.users.find({ 
  country: { $nin: ["US", "CA", "UK"] } 
});

// Comparison with dates
db.events.find({
  timestamp: {
    $gte: ISODate("2024-01-01"),
    $lt: ISODate("2024-02-01")
  }
});

// Comparison with nested fields
db.users.find({ 
  "profile.age": { $gte: 18 } 
});

Logical operators combine multiple conditions for complex queries.

Logical Operator Reference

Examples

$and (explicit and implicit):

// Implicit AND (comma-separated conditions)
db.products.find({ 
  price: { $gte: 100 },
  category: "electronics",
  inStock: true
});

// Explicit $and (needed when querying same field multiple times)
db.products.find({
  $and: [
    { tags: { $elemMatch: { $eq: "sale" } } },
    { tags: { $elemMatch: { $eq: "featured" } } }
  ]
});

$or:

// Match users from different conditions
db.users.find({
  $or: [
    { role: "admin" },
    { "permissions.canEdit": true }
  ]
});

// Combined with other conditions
db.products.find({
  category: "electronics",  // AND
  $or: [
    { brand: "Apple" },
    { price: { $gt: 1000 } }
  ]
});

$not:

// Negate a condition
db.products.find({
  price: { $not: { $gt: 100 } }  // price <= 100 or price doesn't exist
});

// $not with regex
db.users.find({
  email: { $not: /.*@gmail\.com$/ }  // Not a Gmail address
});

$nor:

// Exclude multiple conditions
db.users.find({
  $nor: [
    { status: "banned" },
    { role: "guest" },
    { verified: false }
  ]
});
// Matches users who are NOT banned AND NOT guests AND ARE verified

Document databases excel at querying arrays. MongoDB provides powerful operators for array matching and manipulation.

Array Operator Reference

Examples

Basic Array Matching:

// Match if array CONTAINS the value
db.products.find({ tags: "electronics" });
// Matches: { tags: ["electronics", "sale"] }
// Matches: { tags: ["electronics"] }

// Match if array contains ALL values
db.products.find({ tags: { $all: ["electronics", "sale"] } });
// Matches: { tags: ["electronics", "sale", "featured"] }
// Does NOT match: { tags: ["electronics", "new"] }

// Match exact array (order and content)
db.products.find({ tags: ["electronics", "sale"] });
// Only matches exactly: { tags: ["electronics", "sale"] }

$elemMatch for Complex Conditions:

// Sample document:
// { scores: [{ subject: "math", score: 85 }, { subject: "english", score: 72 }] }

// Find where at least one element matches ALL conditions
db.students.find({
  scores: {
    $elemMatch: {
      subject: "math",
      score: { $gte: 80 }
    }
  }
});

// Without $elemMatch (matches across different elements - usually wrong!):
db.students.find({
  "scores.subject": "math",
  "scores.score": { $gte: 80 }
});
// This could match if math=60 and english=85!

Array Updates:

// Update first matching element using $
db.orders.updateOne(
  { _id: orderId, "items.product": "SKU123" },
  { $set: { "items.$.status": "shipped" } }
);

// Update ALL array elements using $[]
db.products.updateOne(
  { _id: productId },
  { $mul: { "variants.$[].price": 1.1 } }  // 10% price increase
);

// Update specific elements using $[identifier] with arrayFilters
db.orders.updateOne(
  { _id: orderId },
  { $set: { "items.$[item].discount": 10 } },
  { arrayFilters: [{ "item.price": { $gt: 100 } }] }
);
// Only items with price > 100 get the discount

These operators check for field existence, types, and evaluate expressions.

Element Operators

// $exists: Check if field exists
db.users.find({ phone: { $exists: true } });  // Has phone field
db.users.find({ deletedAt: { $exists: false } });  // Not soft-deleted

// $type: Check BSON type
db.data.find({ value: { $type: "string" } });  // value is a string
db.data.find({ value: { $type: "number" } });  // any number type
db.data.find({ _id: { $type: "objectId" } });  // ObjectId type

// $type with number codes
db.data.find({ field: { $type: 2 } });  // 2 = string
db.data.find({ field: { $type: [2, 16, 18] } });  // string or int32 or int64

Evaluation Operators

// $regex: Regular expression matching
db.users.find({ 
  email: { $regex: /@example\.com$/i }  // Case-insensitive
});

// With options
db.users.find({ 
  email: { $regex: "@EXAMPLE\.COM$", $options: "i" }
});

// $expr: Use aggregation expressions in queries
db.products.find({
  $expr: { $gt: ["$soldCount", "$stockCount"] }  // Sold more than in stock
});

// $expr for comparing two fields
db.orders.find({
  $expr: {
    $lt: [
      "$amount",
      { $multiply: ["$budget", 0.8] }  // Amount < 80% of budget
    ]
  }
});

$mod and $where Operators

// $mod: Modulo operation
db.items.find({ quantity: { $mod: [10, 0] } });  // Divisible by 10

// $where: JavaScript expression (use sparingly - slow!)
db.users.find({
  $where: function() {
    return this.firstName.length + this.lastName.length > 20;
  }
});

// Prefer $expr over $where:
db.users.find({
  $expr: {
    $gt: [
      { $add: [
        { $strLenCP: "$firstName" },
        { $strLenCP: "$lastName" }
      ]},
      20
    ]
  }
});

Controlling what data is returned and in what order is essential for performance and usability.

Projection

Projection specifies which fields to include or exclude:

// Include specific fields (1 = include)
db.users.find(
  { status: "active" },
  { name: 1, email: 1, createdAt: 1 }
);
// Returns: { _id: ..., name: ..., email: ..., createdAt: ... }

// Exclude specific fields (0 = exclude)
db.users.find(
  { status: "active" },
  { password: 0, internalNotes: 0 }
);
// Returns all fields EXCEPT password and internalNotes

// Exclude _id
db.users.find(
  { status: "active" },
  { _id: 0, name: 1, email: 1 }
);

// Nested field projection
db.users.find(
  {},
  { "profile.name": 1, "profile.avatar": 1 }
);

Projection Rules:

• Cannot mix inclusion and exclusion (except _id)
• _id is included by default, can be explicitly excluded
• Array projection with $slice, $elemMatch available

Advanced Projection

// $slice: Limit array elements
db.posts.find(
  { _id: postId },
  { comments: { $slice: 10 } }  // First 10 comments
);

db.posts.find(
  { _id: postId },
  { comments: { $slice: -5 } }  // Last 5 comments
);

db.posts.find(
  { _id: postId },
  { comments: { $slice: [10, 5] } }  // Skip 10, take 5
);

// $elemMatch: Project first matching array element
db.products.find(
  { _id: productId },
  { variants: { $elemMatch: { color: "red" } } }
);

// $ positional: Project first matching element (requires match in query)
db.products.find(
  { "variants.color": "red" },
  { "variants.$": 1 }
);

Sorting

// Ascending (1) and descending (-1)
db.products.find().sort({ price: 1 });  // Cheapest first
db.products.find().sort({ createdAt: -1 });  // Newest first

// Multiple fields (order matters)
db.products.find().sort({ 
  category: 1,      // Primary sort
  price: -1         // Secondary sort (within category)
});

// Text score sorting
db.articles.find(
  { $text: { $search: "mongodb performance" } },
  { score: { $meta: "textScore" } }
).sort({ score: { $meta: "textScore" } });

Pagination Patterns

Skip/Limit (simple but inefficient for large offsets):

const page = 5;
const pageSize = 20;

db.products
  .find({ category: "electronics" })
  .sort({ _id: 1 })
  .skip((page - 1) * pageSize)
  .limit(pageSize);

Cursor-based Pagination (efficient for large datasets):

// First page
const firstPage = await db.products
  .find({ category: "electronics" })
  .sort({ _id: 1 })
  .limit(20)
  .toArray();

const lastId = firstPage[firstPage.length - 1]._id;

// Next page - uses index efficiently
const nextPage = await db.products
  .find({ 
    category: "electronics",
    _id: { $gt: lastId }  // Start after last item
  })
  .sort({ _id: 1 })
  .limit(20)
  .toArray();

MongoDB provides built-in text search capabilities, enabling search across string content with linguistic processing.

Creating Text Indexes

// Single field text index
db.articles.createIndex({ content: "text" });

// Multiple fields with weights
db.articles.createIndex(
  { 
    title: "text", 
    content: "text", 
    tags: "text" 
  },
  {
    weights: {
      title: 10,    // Title matches score 10x
      tags: 5,      // Tag matches score 5x
      content: 1    // Content is baseline
    },
    name: "article_text_index",
    default_language: "english"
  }
);

Text Search Queries

// Basic text search
db.articles.find({ $text: { $search: "mongodb performance" } });

// Phrase search (exact phrase)
db.articles.find({ $text: { $search: "\"database optimization\"" } });

// Negation (exclude terms)
db.articles.find({ $text: { $search: "mongodb -deprecated" } });

// Case-sensitive (requires case-sensitive text index)
db.articles.find({ 
  $text: { 
    $search: "MongoDB", 
    $caseSensitive: true 
  } 
});

// With text score for relevance ranking
db.articles.find(
  { $text: { $search: "database performance tuning" } },
  { score: { $meta: "textScore" } }
).sort({ score: { $meta: "textScore" } });

Text Search Features

Stemming and Language Processing:

• "running", "runs", "ran" → stem to "run"
• Stop words ("the", "a", "is") are ignored
• Language-specific processing (30+ languages)

Diacritics:

// Diacritic-insensitive by default
// "café" matches "cafe"

// For diacritic-sensitive:
db.articles.find({ 
  $text: { 
    $search: "café",
    $diacriticSensitive: true 
  } 
});

Limitations of MongoDB Text Search:

• One text index per collection
• Cannot combine $text with $regex in same query
• No fuzzy matching or typo tolerance
• No custom analyzers or tokenizers

For advanced search requirements (fuzzy matching, faceted search, auto-suggest), consider MongoDB Atlas Search (Lucene-based) or external search engines like Elasticsearch.

MongoDB offers powerful geospatial query capabilities for location-based applications.

GeoJSON Format

// Store location as GeoJSON
{
  _id: "store_1",
  name: "Downtown Coffee",
  location: {
    type: "Point",
    coordinates: [-73.97, 40.77]  // [longitude, latitude]
  }
}

// Polygon (area)
{
  _id: "zone_1",
  name: "Manhattan",
  area: {
    type: "Polygon",
    coordinates: [[
      [-74.01, 40.70],
      [-73.97, 40.70],
      [-73.97, 40.80],
      [-74.01, 40.80],
      [-74.01, 40.70]  // Close the polygon
    ]]
  }
}

Geospatial Indexes

// 2dsphere index for GeoJSON (Earth-like sphere)
db.places.createIndex({ location: "2dsphere" });

// 2d index for flat coordinates (legacy, simple use cases)
db.places.createIndex({ location: "2d" });

Geospatial Query Examples

// $near: Find locations near a point (sorted by distance)
db.stores.find({
  location: {
    $near: {
      $geometry: {
        type: "Point",
        coordinates: [-73.99, 40.73]
      },
      $maxDistance: 5000,  // meters
      $minDistance: 100    // meters
    }
  }
});

// $geoWithin: Find locations within a polygon
db.stores.find({
  location: {
    $geoWithin: {
      $geometry: {
        type: "Polygon",
        coordinates: [[...]]  // Polygon vertices
      }
    }
  }
});

// $geoWithin: Find within a circle (using $centerSphere)
db.stores.find({
  location: {
    $geoWithin: {
      $centerSphere: [
        [-73.99, 40.73],     // Center point
        5 / 6378.1           // Radius in radians (5km / Earth radius in km)
      ]
    }
  }
});

// $geoIntersects: Find geometries that intersect
db.routes.find({
  path: {
    $geoIntersects: {
      $geometry: {
        type: "Polygon",
        coordinates: [[...]]  // Area to check
      }
    }
  }
});

We've covered MongoDB's complete query language. Let's consolidate the key concepts:

What's Next:

With thorough knowledge of document querying, we'll explore document database use cases—understanding when document databases are the right choice, common patterns, anti-patterns to avoid, and real-world scenarios where the document model excels.