MongoDB Query Builder

MongoDB Queries Without the Operator Cheat Sheet

MongoDB's query language is powerful and weird. Powerful: arbitrary nested filtering, rich aggregation, geospatial indexes, full-text search, all expressed as nested JSON. Weird: the operators ($gte, $in, $exists, $elemMatch, $regex) look similar but behave differently, and the wrong choice silently returns wrong results. This builder makes the right operator choice obvious and emits the correct syntax.

Query Operators Worth Knowing

Comparison. $eq, $ne, $gt, $gte, $lt, $lte. Mostly intuitive. Watch out for $ne: { field: { $ne: 'x' } } also matches documents where field doesn't exist. Often you want $ne AND $exists: true together.

Array. $in, $nin, $all, $elemMatch, $size. The big trap: $in: [1, 2, 3] matches an array field containing any of those values, or a scalar field equal to any of those values. Both work. But $all: [1, 2, 3] only matches array fields, requiring all three values present. $elemMatch is for when you need multiple conditions to match against the same array element (not separate elements).

Existence and type. $exists, $type. $exists: true matches if the field is present (even if value is null); $ne: null matches if the value is not null (including missing). These are subtly different. For "field is present and not null": { field: { $exists: true, $ne: null } }.

Logical. $and, $or, $not, $nor. Implicit AND when you list multiple fields. Use $or for top-level alternatives, $and when you need multiple conditions on the same field ($and: [{ score: { $gt: 5 } }, { score: { $lt: 10 } }], the implicit AND won't work here because of the operator collision).

String. $regex, $text. $regex is per-document evaluation unless left-anchored AND case-sensitive (/^foo/), then it can use an index. /foo/i (case-insensitive) and /foo/ (unanchored) full-scan. For real text search, use a text index and $text, not $regex.

Geospatial. $near, $geoWithin, $geoIntersects. Require a 2dsphere index. Out of scope for most teams but powerful when you need them.

Index Awareness: The 80% of MongoDB Performance

MongoDB performance is mostly about indexes. A query without an index scans every document; with an index it's logarithmic. The rules:

1. Single-field indexes cover queries on that field. { email: 1 } index covers find({ email: 'x' }).
2. Compound indexes cover queries that filter on a prefix. { status: 1, createdAt: -1 } covers find({ status: 'active' }) and find({ status: 'active', createdAt: { $gt: ... } }) but NOT find({ createdAt: { $gt: ... } }) alone.
3. Sort + filter wants a compound index that matches both. find({ status: 'active' }).sort({ createdAt: -1 }) is fast with { status: 1, createdAt: -1 }.
4. $or is the index-killer. An $or across fields needs an index on each branch; otherwise it scans.

Always run explain('executionStats') on production queries. Look for:

• stage: 'COLLSCAN' → no index used; scan.
• stage: 'IXSCAN' followed by a small nReturned → index used efficiently.
• nReturned close to totalDocsExamined → index is selective.
• nReturned << totalDocsExamined → index scanned a lot to find a few; consider a better-fitting index.

Aggregation Pipeline Patterns

Aggregation is MongoDB's answer to GROUP BY, JOIN, and more. Stages run sequentially; each receives the previous stage's output.

Filter → Group → Sort (top counts by category):

Put $match first, it uses indexes; later stages don't.

Lookup (join):

$lookup is a left outer join; $unwind flattens the resulting array if you expect a single match.

Project (shape):

Use $project late in the pipeline to drop fields you don't need; it reduces document size for downstream stages and final transmission.

Common MongoDB Query Mistakes

Comparing dates as strings. { createdAt: { $gt: '2026-01-01' } }, works only if createdAt is stored as ISO 8601 strings. If stored as BSON Date, you need new Date('2026-01-01'). Mixing types is silently wrong.

Querying nested arrays without $elemMatch. { 'tags.label': 'urgent', 'tags.priority': 'high' } matches documents where any tag has label 'urgent' AND any tag has priority 'high', not necessarily the same tag. Use $elemMatch to require both on the same element.

Forgetting that $ne matches missing fields. { deleted: { $ne: true } } returns documents where deleted is false AND documents where deleted is missing. Often what you want; sometimes a bug.

Updating with the wrong operator. { name: 'x' } as an update replaces the entire document, use { $set: { name: 'x' } } to modify a field. This is a classic MongoDB beginner mistake.

Trusting client-provided _id. If your API accepts _id from the client, an attacker can supply someone else's ID and read/write their data. Always validate ownership server-side.

The Right Workflow

1. Sketch the query in the builder; export to your driver's syntax.
2. Run in a development collection.
3. Verify the results match expectations (use limit(5) for spot checks).
4. Run explain('executionStats') on the production collection structure to verify index usage.
5. Add indexes if needed.
6. Deploy with confidence.

The builder helps with step 1; the rest is on you and your DB tooling.

Privacy

Query construction is purely client-side: dropdowns and inputs assemble a JSON object, the tool renders the result. Field names, which often reveal schema design, business logic, and sensitive column names like ssn_last_four or credit_card_token, never leave the tab. Open DevTools Network during construction: zero outbound requests.