Introduction
A step-by-step guide to help you open, use, and validate Query Studio — the unified query authoring shell in NoSqlStudio. Five tools — find · Visual · SQL · Fluent · Relations — converge into a single query scoped to one `db.collection`, which you then run, explain, export, and save — with EJSON and GridFS in the same shell. Follow from Step 1 to the end, in order.
How to read this manual
Each step has:
- Do — the exact action (click, type, run such-and-such command).
- See — what should happen on screen. This is your “pass / fail”.
- Why — extra context, only when it helps (skip it if you're in a hurry).
Before you start
Concept
What Query Studio is
Query Studio lets you author one MongoDB query from five different angles — a JSON find filter, a Visual Builder, ANSI SQL, a Fluent chain, or $lookup Relations — all targeting a single db.collection. You then Run, Explain, and Export it, with EJSON and GridFS utilities built in.
Heads-up
Query Studio needs an active connection
Query Studio works against a connected MongoDB. It does not write anything to the database by itself — only the queries you explicitly Run touch your data, and the walkthrough below stays read-only.
You will need:
- 1A connected MongoDB with at least one database and a few collections holding sample documents.
- 2Two collections that share a key (for example
orderswith acustomerIdandcustomerswith_id) so you can try a$lookupRelation. - 3Optionally, a second database with a related collection, to try a cross-database relation.
Estimated time for the full walkthrough: ~20 minutes.
Your first query
Open Query Studio and scope it to a single db.collection.
Open Query Studio
With an active connection, open Query Studio: from Home, click the Query Studio card, or use the menu Tools ▸ Shell & CLI ▸ Query Studio (keyboard shortcut Ctrl+Alt+Q).
Query Studio opens empty — the two top selectors show placeholders and nothing is auto-selected.
Query Studio needs a connection to list databases and collections. Nothing is pre-picked, so you always start from a clean, explicit scope.
Pick a database
In the top bar, use the first typeahead selector Select Database — type or pick the database (the list comes from the current connection).
The database is selected, and the second selector repopulates with that database's collections.
Pick a collection
Use the second typeahead selector Select Collection and choose a collection — for example orders.
A namespace: <db>.<collection> chip appears (for example namespace: shop.orders). Every query is now scoped to that namespace (use <db> + db.<collection>…).
The namespace chip is the contract for the whole screen — find, Visual, SQL, Fluent and Relations all build a query against exactly this db.collection.
Filter (find) and the Visual Builder
Author a filter two ways — raw JSON, then the Visual Builder with its smart value editor.
Write a JSON filter
Open the ◆ Filter (find) rail and type a JSON filter, for example:
{ "status": "paid" }The Generated query shows db.<collection>.find({…}).limit(25). Invalid JSON gets a red border and an error message.
Add a Visual Builder condition
Open the 🎯 Visual Builder rail and click + Condition. Choose a field (it lists the collection's attributes; type to filter), an operator (=, ≠, >, ≥, <, ≤, ∈ in, ∉ nin, ∃ exists, ~ regex, type, size, all, mod, elemMatch), a type (string/number/boolean/null/date/ObjectId/JSON), and a value.
The condition is added and the Generated query updates to reflect it.
Use the smart value editor
Watch how the value editor adapts to the field and type: a boolean field gives a true/false select, a date field gives a date-picker, and a field whose sample has ≤25 distinct values (an “enum”) gives a dropdown of the values seen.
For an enum field you pick from a dropdown; for a boolean you pick true/false; for a date you pick from a calendar — no need to hand-type the value.
The editor samples your data to offer the right control, instead of leaving every value as free text.
Search values on a high-cardinality field
Pick a field with many distinct values. If it is indexed, type to search by prefix on the index. If it is not indexed, click Sample 1000 docs ($sample) to draw candidate values.
Matching values appear as you type (indexed) or after sampling (non-indexed).
Concept
Query Studio never runs a global distinct(). On high-cardinality fields it uses an index prefix search or a bounded $sample of 1000 docs, so it stays cheap on big collections.
Nest conditions in groups
Click + Group to nest a group, and set its combinator to AND, OR, or NOR. Use × to remove a condition or a group.
Conditions nest under the group's combinator, and the Generated query reflects the boolean logic.
SQL → Mongo and Fluent
Author the same query as ANSI SQL or as a Mongoose-style chain, and watch your work survive a tool switch.
Write SQL and apply it
Open the 🔤 SQL → Mongo rail, write ANSI SQL (or click example 1 / 2), then click Apply →.
The SQL is translated into a pipeline, with a confirmation like ✓ applied · pipeline (N stages).
Write a Fluent chain and apply it
Open the 🧩 Fluent rail, write a Mongoose-style chain (or click example 1 / 2), for example:
db.users.where('age').gte(18).sort('-age').limit(50)Click Apply →.
The chain becomes the Generated query, with a source: tag showing it came from Fluent.
Confirm a tool switch preserves your work
Switch between the rails (Filter, Visual Builder, SQL, Fluent) and back.
What you built in each tool is preserved, and the source: tag on the Generated query indicates which tool produced the current query.
You can sketch in one tool, refine in another, and never lose the earlier draft.
Relations ($lookup)
Join one or more collections with $lookup, including cross-database joins that run client-side.
Add a relation
Open the 🔗 Relations ($lookup) rail and click + Relation. Choose the relation's database and collection (from) — when you pick it, its attributes load into the pickers.
A relation block appears, and the related collection's fields are available to map.
Name the output and set join keys
Set as — the output field name (defaults to the collection name). Then set the equality join keys: a pair of base field ↔ related field. For a composite key, click + pair to add more pairs; if the columns share a name, click the “in common:” chips to match same-named fields automatically.
The join keys are mapped, and the Generated query shows the $lookup being built.
Choose cardinality
Set the cardinality: 1:N (the result is an array) or 1:1 (the result is unwound with $unwind).
1:N keeps the joined docs as an array under as; 1:1 flattens it to a single embedded document.
Filter the related side and add an optional $match
Optionally fill filter related (JSON) — for same-db relations it becomes a sub-pipeline inside the $lookup; for cross-db it becomes a find on the related collection. Optionally fill $match (JSON) — same-db: applied after the $lookup and may use pulled-in fields (for example { "orders.total": { "$gt": 100 } }); cross-db: it filters the base collection.
The Generated query incorporates the sub-pipeline and/or the $match stage.
Let Query Studio suggest relations
Click ✨ Suggest relations to infer relations (foreign keys + shared fields) and auto-fill the pairs and cardinality. Tick cross-db to infer relations between databases (a wider sample, slower).
Suggested relations appear with their join pairs and cardinality already filled in.
Build a cross-database relation
In a relation, choose a database other than the base database.
A cross-db (client-side join) badge appears. Because native $lookup is same-database only, the Generated query shows a plan (base + related + merge) instead of a single pipeline, and Run performs the join in the app by key equality.
Heads-up
Known limit: on a cross-database join the related side is read with a cap of 2000 docs. A very large related collection may be truncated.
Run, Explain, and Export
Generate the query in the format you want, run it, explain it, and page through results.
Choose an export format and copy
In the right-hand panel, use the Generated query format selector to switch between mongosh / JSON / Node.js / Python, then click Copy.
The query is shown in the chosen format, and Copy copies exactly that format to the clipboard.
Run the query
Click Run ▶.
The query executes and returns documents. ObjectId() / ISODate() are materialized as real BSON in the Run.
Explain the query
Click Explain.
The plan (queryPlanner) is shown — for both find and aggregate queries.
Browse results and page
In the result area, toggle between Table and JSON, set docs/page (10/25/50/100), and navigate with ‹ ›.
The results render as a table or as JSON, and the pager shows “page N” as you move through them.
Library and history
Save query snapshots, reload them, and see a history of every Run — all persisted across restarts.
Save a snapshot to the Library
In the query panel, click ★ Library, then Save and give it a name.
A complete snapshot is stored — the db/collection/tool plus the filter / visual / SQL / fluent / relations state.
Reload a saved query and review history
Under Saved, click an entry to reload it (× deletes it). Under History, each Run is recorded — click an entry to reload it, or clear to empty the history.
Clicking a saved entry restores the full query state; the History list grows by one entry per Run.
Confirm persistence
Save a query, run another, then close and reopen the app.
Your saved queries and history are still there — the Library persists in localStorage and survives closing and reopening the app.
Utilities (EJSON and GridFS)
Two helpers live in the same shell: an Extended JSON converter and a GridFS browser.
Convert with the EJSON utility
Open the 🔁 EJSON utility, paste Extended JSON, and use → To shell and ← To EJSON; toggle canonical / relaxed.
The converter rewrites ObjectId / ISODate / Decimal128 and similar types between EJSON and shell syntax, in the chosen canonical or relaxed form.
Browse files with GridFS
Open the 🗃️ GridFS utility, enter the bucket (fs), and it lists the files in <db>.<bucket>.files. Use search filename… to narrow the list, View to preview an image or text file, and Download to rebuild the file from its .chunks.
The bucket's files are listed; View shows a preview and Download reassembles and saves the full file.
Theme
Switch the theme
Use the Theme menu (light / dark / themes) and watch Query Studio follow it.
The background, surfaces, text, borders, and the code highlighting of the Generated query all adapt to the chosen theme, staying legible in Light as well as Dark.
Cleanup (when you're done)
Nothing destructive is required. Query Studio writes nothing to the database by itself — only the queries you Run touch your data, and this walkthrough stays read-only.
If you want a clean slate, close the Query Studio tab and, in the ★ Library, use clear to empty the Run history. Your saved queries stay in localStorage until you delete them with ×.
The tab closes and the history is empty; your database is untouched.
Summary of what you validated
| Stage | Feature |
|---|---|
| 1 | Open Query Studio and scope it to a single db.collection |
| 2 | Author a JSON filter and build conditions in the Visual Builder with its smart value editor |
| 3 | Translate ANSI SQL and a Fluent chain into a query, preserved across tool switches |
| 4 | Join collections with $lookup Relations, including a cross-database client-side join |
| 5 | Run, Explain, export in mongosh/JSON/Node.js/Python, and page through results |
| 6 | Save snapshots to the Library, reload them, and review per-Run history that persists |
| 7 | Convert Extended JSON and browse GridFS files (View / Download) |
| 8 | Query Studio follows the Theme menu |