Introdução
Um guia passo a passo para te ajudar a abrir, usar e validar o Query Studio — o shell unificado de autoria de queries do NoSqlStudio. Cinco ferramentas — find · Visual · SQL · Fluent · Relações — convergem numa query única escopada a uma `db.coleção`, que você então roda, explica, exporta e salva — com EJSON e GridFS no mesmo shell. Siga do Passo 1 até o fim, em ordem.
Como ler este manual
Cada passo tem:
- Faça — a ação exata (clicar, digitar, rodar tal comando).
- Veja — o que deve acontecer na tela. Esse é o seu “passou / falhou”.
- Por quê — contexto adicional, só quando ajuda (pule se estiver com pressa).
Antes de começar
Conceito
O que é o Query Studio
O Query Studio deixa você montar uma única query MongoDB por cinco ângulos diferentes — um filtro find em JSON, um Visual Builder, ANSI SQL, uma cadeia Fluent ou Relações $lookup — todos mirando uma única db.coleção. Depois você roda, explica e exporta, com utilitários de EJSON e GridFS embutidos.
Atenção
O Query Studio precisa de conexão ativa
O Query Studio funciona sobre um MongoDB conectado. Ele não escreve nada no banco por conta própria — só as queries que você explicitamente roda tocam seus dados, e o walkthrough abaixo é todo somente-leitura.
Você vai precisar de:
- 1Um MongoDB conectado com pelo menos um banco e algumas coleções com documentos de exemplo.
- 2Duas coleções que compartilham uma chave (por exemplo
orderscomcustomerIdecustomerscom_id) para experimentar uma Relação$lookup. - 3Opcionalmente, um segundo banco com uma coleção relacionada, para experimentar uma relação cross-database.
Tempo estimado para o walkthrough completo: ~20 minutos.
Sua primeira query
Abra o Query Studio e escope-o a uma única db.coleção.
Abra o Query Studio
Com uma conexão ativa, abra o Query Studio: na Home, clique no card Query Studio, ou use o menu Tools ▸ Shell & CLI ▸ Query Studio (atalho de teclado Ctrl+Alt+Q).
O Query Studio abre vazio — os dois seletores do topo mostram placeholders e nada é auto-selecionado.
O Query Studio precisa de conexão para listar bancos e coleções. Nada vem pré-escolhido, então você sempre começa de um escopo limpo e explícito.
Escolha o banco
Na barra do topo, use o primeiro seletor com busca (typeahead) Select Database — digite ou escolha o banco (a lista vem da conexão atual).
O banco é selecionado, e o segundo seletor repopula com as coleções desse banco.
Escolha a coleção
Use o segundo seletor com busca (typeahead) Select Collection e escolha uma coleção — por exemplo orders.
Aparece o chip namespace: <db>.<coleção> (por exemplo namespace: shop.orders). Toda query passa a ser escopada a esse namespace (use <db> + db.<coleção>…).
O chip de namespace é o contrato da tela inteira — find, Visual, SQL, Fluent e Relações montam a query exatamente sobre essa db.coleção.
Filtro (find) e o Visual Builder
Monte um filtro de duas formas — JSON cru, e depois o Visual Builder com seu editor de valor inteligente.
Escreva um filtro JSON
Abra o rail ◆ Filtro (find) e digite um filtro JSON, por exemplo:
{ "status": "paid" }A Query gerada mostra db.<coleção>.find({…}).limit(25). JSON inválido fica com borda vermelha e uma mensagem de erro.
Adicione uma condição no Visual Builder
Abra o rail 🎯 Visual Builder e clique em + Condição. Escolha um campo (lista os atributos da coleção; digite para filtrar), um operador (=, ≠, >, ≥, <, ≤, ∈ in, ∉ nin, ∃ exists, ~ regex, type, size, all, mod, elemMatch), um tipo (string/number/boolean/null/date/ObjectId/JSON) e um valor.
A condição é adicionada e a Query gerada se atualiza para refleti-la.
Use o editor de valor inteligente
Veja como o editor de valor se adapta ao campo e ao tipo: um campo boolean vira um select true/false, um campo date vira um date-picker, e um campo cuja amostra tem ≤25 valores distintos (um “enum”) vira um dropdown com os valores vistos.
Num campo enum você escolhe num dropdown; num boolean você escolhe true/false; numa data você escolhe num calendário — sem precisar digitar o valor à mão.
O editor amostra seus dados para oferecer o controle certo, em vez de deixar todo valor como texto livre.
Busque valores num campo de alta cardinalidade
Escolha um campo com muitos valores distintos. Se ele for indexado, digite para buscar por prefixo no índice. Se não for indexado, clique em Amostrar 1000 docs ($sample) para puxar valores candidatos.
Os valores que casam aparecem conforme você digita (indexado) ou após a amostragem (não indexado).
Conceito
O Query Studio nunca roda um distinct() global. Em campos de alta cardinalidade ele usa busca por prefixo no índice ou um $sample limitado a 1000 docs, então continua barato em coleções grandes.
Aninhe condições em grupos
Clique em + Grupo para aninhar um grupo, e defina seu combinador como AND, OR ou NOR. Use × para remover uma condição ou um grupo.
As condições aninham sob o combinador do grupo, e a Query gerada reflete a lógica booleana.
SQL → Mongo e Fluent
Monte a mesma query como ANSI SQL ou como uma cadeia estilo Mongoose, e veja seu trabalho sobreviver à troca de ferramenta.
Escreva SQL e aplique
Abra o rail 🔤 SQL → Mongo, escreva ANSI SQL (ou clique em exemplo 1 / 2), depois clique em Aplicar →.
O SQL é traduzido num pipeline, com uma confirmação como ✓ aplicado · pipeline (N estágios).
Escreva uma cadeia Fluent e aplique
Abra o rail 🧩 Fluent, escreva uma cadeia estilo Mongoose (ou clique em exemplo 1 / 2), por exemplo:
db.users.where('age').gte(18).sort('-age').limit(50)Clique em Aplicar →.
A cadeia vira a Query gerada, com uma tag fonte: indicando que veio do Fluent.
Confirme que trocar de ferramenta preserva o trabalho
Alterne entre os rails (Filtro, Visual Builder, SQL, Fluent) e volte.
O que você montou em cada ferramenta é preservado, e a tag fonte: na Query gerada indica qual ferramenta produziu a query atual.
Você pode esboçar numa ferramenta, refinar em outra, e nunca perder o rascunho anterior.
Relações ($lookup)
Relacione uma ou N coleções com $lookup, incluindo junções cross-database que rodam no cliente.
Adicione uma relação
Abra o rail 🔗 Relações ($lookup) e clique em + Relação. Escolha o database e a coleção (from) da relação — ao escolher, os atributos dela carregam nos pickers.
Aparece um bloco de relação, e os campos da coleção relacionada ficam disponíveis para mapear.
Nomeie a saída e defina as chaves de junção
Defina o as — o nome do campo de saída (default = nome da coleção). Depois defina as chaves de junção (igualdade): um par campo base ↔ campo relacionado. Para uma chave composta, clique em + par para adicionar mais pares; se as colunas têm o mesmo nome, clique nos chips “em comum:” para casar campos de mesmo nome automaticamente.
As chaves de junção são mapeadas, e a Query gerada mostra o $lookup sendo montado.
Escolha a cardinalidade
Defina a cardinalidade: 1:N (o resultado é um array) ou 1:1 (o resultado é achatado com $unwind).
1:N mantém os docs relacionados como um array sob o as; 1:1 achata para um único documento embutido.
Filtre a relacionada e adicione um $match opcional
Opcionalmente preencha filtrar relacionada (JSON) — em relações mesmo-db vira um sub-pipeline dentro do $lookup; em cross-db vira um find na coleção relacionada. Opcionalmente preencha $match opcional (JSON) — mesmo-db: aplicado após o $lookup e pode usar campos puxados (por exemplo { "orders.total": { "$gt": 100 } }); cross-db: filtra a coleção base.
A Query gerada incorpora o sub-pipeline e/ou o estágio $match.
Deixe o Query Studio sugerir relações
Clique em ✨ Sugerir relações para inferir relações (chaves estrangeiras + campos compartilhados) e preencher automaticamente os pares e a cardinalidade. Marque cross-db para inferir relações entre databases (amostra mais ampla, mais lenta).
As relações sugeridas aparecem com seus pares de junção e cardinalidade já preenchidos.
Monte uma relação cross-database
Numa relação, escolha um database diferente do database base.
Aparece o selo cross-db (junção no cliente). Como o $lookup nativo é só mesmo-db, a Query gerada mostra um plano (base + relacionadas + merge) em vez de um único pipeline, e o Run executa a junção no app por igualdade de chave.
Atenção
Limite conhecido: numa junção cross-database o lado relacionado é lido com teto de 2000 docs. Uma coleção relacionada muito grande pode truncar.
Rodar, Explicar e Exportar
Gere a query no formato que quiser, rode-a, explique-a e pagine os resultados.
Escolha um formato de exportação e copie
No painel da direita, use o seletor de formato da Query gerada para alternar entre mongosh / JSON / Node.js / Python, depois clique em Copiar.
A query é mostrada no formato escolhido, e Copiar copia exatamente esse formato para a área de transferência.
Rode a query
Clique em Run ▶.
A query executa e traz os documentos. ObjectId() / ISODate() são materializados em BSON real no Run.
Explique a query
Clique em Explain.
O plano (queryPlanner) é mostrado — tanto para find quanto para aggregate.
Navegue pelos resultados e pagine
Na área de resultado, alterne entre Tabela e JSON, ajuste docs/página (10/25/50/100) e navegue com ‹ ›.
Os resultados renderizam como tabela ou como JSON, e o paginador mostra “pág N” conforme você avança.
Biblioteca e histórico
Salve snapshots de query, recarregue-os e veja um histórico de cada Run — tudo persistido entre reinícios.
Salve um snapshot na Biblioteca
No painel da query, clique em ★ Biblioteca, depois em Salvar e dê um nome.
Um snapshot completo é gravado — o db/coleção/ferramenta mais o estado de filtro / visual / SQL / fluent / relações.
Recarregue uma query salva e revise o histórico
Em Salvos, clique numa entrada para recarregar (o × exclui). Em Histórico, cada Run é registrado — clique numa entrada para recarregar, ou limpar para zerar o histórico.
Clicar numa entrada salva restaura o estado completo da query; a lista de Histórico cresce em uma entrada por Run.
Confirme a persistência
Salve uma query, rode outra, depois feche e reabra o app.
Suas queries salvas e o histórico continuam lá — a Biblioteca persiste em localStorage e sobrevive a fechar e reabrir o app.
Utilitários (EJSON e GridFS)
Dois auxiliares vivem no mesmo shell: um conversor de Extended JSON e um navegador de GridFS.
Converta com o utilitário EJSON
Abra o utilitário 🔁 EJSON, cole Extended JSON e use → Para shell e ← Para EJSON; alterne canonical / relaxed.
O conversor reescreve ObjectId / ISODate / Decimal128 e tipos similares entre EJSON e a sintaxe do shell, na forma canonical ou relaxed escolhida.
Navegue arquivos com o GridFS
Abra o utilitário 🗃️ GridFS, informe o bucket (fs), e ele lista os arquivos de <db>.<bucket>.files. Use buscar filename… para filtrar a lista, Ver para um preview de imagem ou texto, e Baixar para remontar o arquivo a partir dos seus .chunks.
Os arquivos do bucket são listados; Ver mostra um preview e Baixar remonta e salva o arquivo completo.
Tema
Troque o tema
Use o menu Theme (claro / escuro / temas) e veja o Query Studio acompanhar.
O fundo, as superfícies, o texto, as bordas e o realce de código da Query gerada se adaptam ao tema escolhido, mantendo a legibilidade tanto no Light quanto no Dark.
Limpeza (quando terminar)
Nada destrutivo é necessário. O Query Studio não escreve nada no banco por conta própria — só as queries que você roda tocam seus dados, e este walkthrough é todo somente-leitura.
Se quiser começar do zero, feche a aba do Query Studio e, na ★ Biblioteca, use limpar para zerar o histórico de Run. Suas queries salvas continuam no localStorage até você excluí-las com ×.
A aba fecha e o histórico fica vazio; seu banco fica intacto.
Resumo do que você validou
| Etapa | Recurso |
|---|---|
| 1 | Abrir o Query Studio e escopá-lo a uma única db.coleção |
| 2 | Montar um filtro JSON e criar condições no Visual Builder com seu editor de valor inteligente |
| 3 | Traduzir ANSI SQL e uma cadeia Fluent numa query, preservada ao trocar de ferramenta |
| 4 | Relacionar coleções com Relações $lookup, incluindo uma junção cross-database no cliente |
| 5 | Rodar, Explicar, exportar em mongosh/JSON/Node.js/Python e paginar os resultados |
| 6 | Salvar snapshots na Biblioteca, recarregá-los e revisar o histórico por Run que persiste |
| 7 | Converter Extended JSON e navegar arquivos GridFS (Ver / Baixar) |
| 8 | O Query Studio segue o menu Theme |