Introducción
Una guía paso a paso para ayudarte a abrir, usar y validar Query Studio — el shell unificado de autoría de queries de NoSqlStudio. Cinco herramientas — find · Visual · SQL · Fluent · Relaciones — convergen en una query única acotada a una `db.colección`, que luego ejecutas, explicas, exportas y guardas — con EJSON y GridFS en el mismo shell. Sigue del Paso 1 hasta el final, en orden.
Cómo leer este manual
Cada paso tiene:
- Haz — la acción exacta (hacer clic, escribir, ejecutar tal comando).
- Mira — qué debe ocurrir en pantalla. Este es tu “pasa / falla”.
- Por qué — contexto adicional, solo cuando ayuda (sáltalo si vas con prisa).
Antes de empezar
Concepto
Qué es Query Studio
Query Studio te permite componer una sola query de MongoDB desde cinco ángulos distintos — un filtro find en JSON, un Visual Builder, ANSI SQL, una cadena Fluent o Relaciones $lookup — todos apuntando a una única db.colección. Luego la ejecutas, explicas y exportas, con utilidades de EJSON y GridFS integradas.
Atención
Query Studio necesita una conexión activa
Query Studio funciona sobre un MongoDB conectado. No escribe nada en la base por sí mismo — solo las queries que ejecutas explícitamente tocan tus datos, y el recorrido de abajo es todo de solo lectura.
Vas a necesitar:
- 1Un MongoDB conectado con al menos una base y algunas colecciones con documentos de ejemplo.
- 2Dos colecciones que compartan una clave (por ejemplo
ordersconcustomerIdycustomerscon_id) para probar una Relación$lookup. - 3Opcionalmente, una segunda base con una colección relacionada, para probar una relación cross-database.
Tiempo estimado para el recorrido completo: ~20 minutos.
Tu primera query
Abre Query Studio y acótalo a una única db.colección.
Abre Query Studio
Con una conexión activa, abre Query Studio: desde el Home, haz clic en la tarjeta Query Studio, o usa el menú Tools ▸ Shell & CLI ▸ Query Studio (atajo de teclado Ctrl+Alt+Q).
Query Studio abre vacío — los dos selectores de arriba muestran placeholders y nada se autoselecciona.
Query Studio necesita una conexión para listar bases y colecciones. Nada viene preelegido, así que siempre arrancas desde un alcance limpio y explícito.
Elige la base
En la barra superior, usa el primer selector con búsqueda (typeahead) Select Database — escribe o elige la base (la lista viene de la conexión actual).
La base queda seleccionada, y el segundo selector se repuebla con las colecciones de esa base.
Elige la colección
Usa el segundo selector con búsqueda (typeahead) Select Collection y elige una colección — por ejemplo orders.
Aparece el chip namespace: <db>.<colección> (por ejemplo namespace: shop.orders). Toda query queda ahora acotada a ese namespace (use <db> + db.<colección>…).
El chip de namespace es el contrato de toda la pantalla — find, Visual, SQL, Fluent y Relaciones construyen la query exactamente sobre esa db.colección.
Filtro (find) y el Visual Builder
Compón un filtro de dos formas — JSON crudo, y luego el Visual Builder con su editor de valor inteligente.
Escribe un filtro JSON
Abre el rail ◆ Filtro (find) y escribe un filtro JSON, por ejemplo:
{ "status": "paid" }La Query generada muestra db.<colección>.find({…}).limit(25). Un JSON inválido queda con borde rojo y un mensaje de error.
Agrega una condición en el Visual Builder
Abre el rail 🎯 Visual Builder y haz clic en + Condición. Elige un campo (lista los atributos de la colección; escribe para filtrar), un operador (=, ≠, >, ≥, <, ≤, ∈ in, ∉ nin, ∃ exists, ~ regex, type, size, all, mod, elemMatch), un tipo (string/number/boolean/null/date/ObjectId/JSON) y un valor.
La condición se agrega y la Query generada se actualiza para reflejarla.
Usa el editor de valor inteligente
Observa cómo el editor de valor se adapta al campo y al tipo: un campo boolean da un select true/false, un campo date da un date-picker, y un campo cuya muestra tiene ≤25 valores distintos (un “enum”) da un dropdown con los valores vistos.
En un campo enum eliges de un dropdown; en un boolean eliges true/false; en una fecha eliges de un calendario — sin tener que escribir el valor a mano.
El editor muestrea tus datos para ofrecer el control adecuado, en vez de dejar cada valor como texto libre.
Busca valores en un campo de alta cardinalidad
Elige un campo con muchos valores distintos. Si está indexado, escribe para buscar por prefijo en el índice. Si no está indexado, haz clic en Muestrear 1000 docs ($sample) para traer valores candidatos.
Los valores que coinciden aparecen a medida que escribes (indexado) o tras el muestreo (no indexado).
Concepto
Query Studio nunca ejecuta un distinct() global. En campos de alta cardinalidad usa una búsqueda por prefijo en el índice o un $sample acotado a 1000 docs, así se mantiene económico en colecciones grandes.
Anida condiciones en grupos
Haz clic en + Grupo para anidar un grupo, y define su combinador como AND, OR o NOR. Usa × para quitar una condición o un grupo.
Las condiciones se anidan bajo el combinador del grupo, y la Query generada refleja la lógica booleana.
SQL → Mongo y Fluent
Compón la misma query como ANSI SQL o como una cadena estilo Mongoose, y mira tu trabajo sobrevivir al cambio de herramienta.
Escribe SQL y aplícalo
Abre el rail 🔤 SQL → Mongo, escribe ANSI SQL (o haz clic en ejemplo 1 / 2), luego haz clic en Aplicar →.
El SQL se traduce en un pipeline, con una confirmación como ✓ aplicado · pipeline (N estágios).
Escribe una cadena Fluent y aplícala
Abre el rail 🧩 Fluent, escribe una cadena estilo Mongoose (o haz clic en ejemplo 1 / 2), por ejemplo:
db.users.where('age').gte(18).sort('-age').limit(50)Haz clic en Aplicar →.
La cadena se convierte en la Query generada, con una etiqueta fonte: que indica que vino de Fluent.
Confirma que cambiar de herramienta preserva el trabajo
Alterna entre los rails (Filtro, Visual Builder, SQL, Fluent) y vuelve.
Lo que armaste en cada herramienta se preserva, y la etiqueta fonte: en la Query generada indica qué herramienta produjo la query actual.
Puedes bocetar en una herramienta, refinar en otra, y nunca perder el borrador anterior.
Relaciones ($lookup)
Relaciona una o N colecciones con $lookup, incluyendo joins cross-database que corren en el cliente.
Agrega una relación
Abre el rail 🔗 Relaciones ($lookup) y haz clic en + Relación. Elige el database y la colección (from) de la relación — al elegirla, sus atributos cargan en los pickers.
Aparece un bloque de relación, y los campos de la colección relacionada quedan disponibles para mapear.
Nombra la salida y define las claves de join
Define el as — el nombre del campo de salida (por defecto = nombre de la colección). Luego define las claves de join (igualdad): un par campo base ↔ campo relacionado. Para una clave compuesta, haz clic en + par para agregar más pares; si las columnas comparten nombre, haz clic en los chips “en común:” para emparejar campos del mismo nombre automáticamente.
Las claves de join quedan mapeadas, y la Query generada muestra el $lookup que se está construyendo.
Elige la cardinalidad
Define la cardinalidad: 1:N (el resultado es un array) o 1:1 (el resultado se aplana con $unwind).
1:N mantiene los docs relacionados como un array bajo el as; 1:1 lo aplana a un único documento embebido.
Filtra la relacionada y agrega un $match opcional
Opcionalmente llena filtrar relacionada (JSON) — en relaciones mismo-db se vuelve un sub-pipeline dentro del $lookup; en cross-db se vuelve un find en la colección relacionada. Opcionalmente llena $match opcional (JSON) — mismo-db: aplicado tras el $lookup y puede usar campos traídos (por ejemplo { "orders.total": { "$gt": 100 } }); cross-db: filtra la colección base.
La Query generada incorpora el sub-pipeline y/o la etapa $match.
Deja que Query Studio sugiera relaciones
Haz clic en ✨ Sugerir relaciones para inferir relaciones (claves foráneas + campos compartidos) y autocompletar los pares y la cardinalidad. Marca cross-db para inferir relaciones entre databases (muestra más amplia, más lenta).
Las relaciones sugeridas aparecen con sus pares de join y cardinalidad ya completados.
Arma una relación cross-database
En una relación, elige un database distinto del database base.
Aparece el distintivo cross-db (join en el cliente). Como el $lookup nativo es solo mismo-db, la Query generada muestra un plan (base + relacionadas + merge) en vez de un único pipeline, y el Run ejecuta el join en la app por igualdad de clave.
Atención
Límite conocido: en un join cross-database el lado relacionado se lee con un tope de 2000 docs. Una colección relacionada muy grande puede truncarse.
Ejecutar, Explicar y Exportar
Genera la query en el formato que quieras, ejecútala, explícala y pagina los resultados.
Elige un formato de exportación y copia
En el panel derecho, usa el selector de formato de la Query generada para alternar entre mongosh / JSON / Node.js / Python, luego haz clic en Copiar.
La query se muestra en el formato elegido, y Copiar copia exactamente ese formato al portapapeles.
Ejecuta la query
Haz clic en Run ▶.
La query se ejecuta y trae los documentos. ObjectId() / ISODate() se materializan como BSON real en el Run.
Explica la query
Haz clic en Explain.
Se muestra el plan (queryPlanner) — tanto para find como para aggregate.
Navega los resultados y pagina
En el área de resultado, alterna entre Tabla y JSON, ajusta docs/página (10/25/50/100) y navega con ‹ ›.
Los resultados se renderizan como tabla o como JSON, y el paginador muestra “pág N” a medida que avanzas.
Biblioteca e historial
Guarda snapshots de query, recárgalos y mira un historial de cada Run — todo persistido entre reinicios.
Guarda un snapshot en la Biblioteca
En el panel de la query, haz clic en ★ Biblioteca, luego en Guardar y dale un nombre.
Se almacena un snapshot completo — la db/colección/herramienta más el estado de filtro / visual / SQL / fluent / relaciones.
Recarga una query guardada y revisa el historial
En Guardados, haz clic en una entrada para recargarla (el × la elimina). En Historial, cada Run queda registrado — haz clic en una entrada para recargarla, o limpiar para vaciar el historial.
Hacer clic en una entrada guardada restaura el estado completo de la query; la lista de Historial crece en una entrada por Run.
Confirma la persistencia
Guarda una query, ejecuta otra, luego cierra y vuelve a abrir la app.
Tus queries guardadas y el historial siguen ahí — la Biblioteca persiste en localStorage y sobrevive a cerrar y reabrir la app.
Utilidades (EJSON y GridFS)
Dos auxiliares viven en el mismo shell: un conversor de Extended JSON y un navegador de GridFS.
Convierte con la utilidad EJSON
Abre la utilidad 🔁 EJSON, pega Extended JSON y usa → A shell y ← A EJSON; alterna canonical / relaxed.
El conversor reescribe ObjectId / ISODate / Decimal128 y tipos similares entre EJSON y la sintaxis del shell, en la forma canonical o relaxed elegida.
Navega archivos con GridFS
Abre la utilidad 🗃️ GridFS, indica el bucket (fs), y lista los archivos de <db>.<bucket>.files. Usa buscar filename… para filtrar la lista, Ver para una vista previa de imagen o texto, y Descargar para rearmar el archivo a partir de sus .chunks.
Los archivos del bucket se listan; Ver muestra una vista previa y Descargar rearma y guarda el archivo completo.
Tema
Cambia el tema
Usa el menú Theme (claro / oscuro / temas) y mira a Query Studio seguirlo.
El fondo, las superficies, el texto, los bordes y el resaltado de código de la Query generada se adaptan al tema elegido, manteniendo la legibilidad tanto en Light como en Dark.
Limpieza (cuando termines)
No se requiere nada destructivo. Query Studio no escribe nada en la base por sí mismo — solo las queries que ejecutas tocan tus datos, y este recorrido es todo de solo lectura.
Si quieres empezar de cero, cierra la pestaña de Query Studio y, en la ★ Biblioteca, usa limpiar para vaciar el historial de Run. Tus queries guardadas siguen en localStorage hasta que las elimines con ×.
La pestaña se cierra y el historial queda vacío; tu base queda intacta.
Resumen de lo que validaste
| Etapa | Funcionalidad |
|---|---|
| 1 | Abrir Query Studio y acotarlo a una única db.colección |
| 2 | Componer un filtro JSON y crear condiciones en el Visual Builder con su editor de valor inteligente |
| 3 | Traducir ANSI SQL y una cadena Fluent en una query, preservada al cambiar de herramienta |
| 4 | Relacionar colecciones con Relaciones $lookup, incluyendo un join cross-database en el cliente |
| 5 | Ejecutar, Explicar, exportar en mongosh/JSON/Node.js/Python y paginar los resultados |
| 6 | Guardar snapshots en la Biblioteca, recargarlos y revisar el historial por Run que persiste |
| 7 | Convertir Extended JSON y navegar archivos GridFS (Ver / Descargar) |
| 8 | Query Studio sigue el menú Theme |