🧠 NeuroQuery

AI-powered Natural Language Interface for MongoDB

NeuroQuery allows users to query MongoDB databases using plain English instead of writing complex queries.
It combines AI query generation, schema inference, validation, and explainability to provide a safe and transparent way to interact with MongoDB.

Built for developers, analysts, and non-technical users, NeuroQuery transforms MongoDB into an intelligent self-service data assistant.

---

🚀 Features

✅ Natural Language Queries
Ask questions like:

"Show customers who signed up last month"

✅ Automatic Schema Inference
NeuroQuery samples MongoDB documents to understand fields and data types.

✅ AI Query Generation
Uses LangChain + Ollama to convert natural language into MongoDB queries.

✅ Query Validation
Detects risky operations such as:

• global deletes
• unsafe updates
• destructive queries

✅ Query Explainability
Shows a human-readable explanation before the query executes.

✅ Cost Estimation & Optimization Hints
Detects:

• collection scans
• missing indexes

and suggests improvements.

✅ Safe Query Execution

✅ Pagination & Result Views

• Table view
• JSON viewer

✅ CSV Export

✅ Query History Logs

✅ Role-Based Access Control

• Admin
• Developer
• ReadOnly

✅ Database Explorer

• List databases
• List collections

---

🏗 Architecture

NeuroQuery follows a modular AI-driven architecture.

Frontend (React + Vite + Tailwind)
⬇
Backend API (Node.js + Express)
⬇
AI Layer (LangChain + Ollama)
⬇
MongoDB

Flow:

1. User enters a natural language query
2. Frontend sends request to backend
3. Backend gathers schema context
4. LLM generates MongoDB query
5. Query is validated
6. Query is explained
7. Query executes safely
8. Results return to frontend

---

🛠 Tech Stack

Frontend

React (Vite)
Tailwind CSS
Axios
JSON Viewer

Backend

Node.js
Express.js
MongoDB Native Driver
JWT Authentication

AI Layer

LangChain
Ollama (local LLM)
Model: llama3.1:8b

---

📡 Backend API Endpoints

Authentication

POST /api/auth/login

Query Processing

POST /api/query/generate
POST /api/query/validate
POST /api/query/explain
POST /api/query/execute

Query History

GET /api/query/history

---

⚙️ Environment Variables

Backend (.env)

PORT
MONGODB_URI
MONGODB_DB

JWT_SECRET

OLLAMA_BASE_URL
OLLAMA_MODEL

REDIS_URL (optional)

ADMIN_EMAIL
ADMIN_PASSWORD
ADMIN_ROLE

CORS_ORIGIN

Example:

PORT=8080
MONGODB_URI=mongodb://localhost:27017
MONGODB_DB=testdb

JWT_SECRET=supersecret

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1:8b

ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=admin123
ADMIN_ROLE=Admin

---

Frontend (.env)

VITE_API_URL=http://localhost:8080

---

🧑‍💻 Local Development Setup

1 Install dependencies

From project root:

npm install
npm --prefix backend install
npm --prefix frontend install

---

2 Configure environment

Copy environment files.

backend/.env.example → backend/.env

frontend/.env.example → frontend/.env

Update values as needed.

---

3 Run Ollama locally

Install Ollama:

https://ollama.ai

Pull the model:

ollama run llama3.1:8b

Ensure these match your configuration:

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.1:8b

---

4 Start the application

From project root:

npm run dev

Frontend:

http://localhost:5173

Backend:

http://localhost:8080

---

🐳 Run with Docker

Run the full stack using Docker:

docker compose up --build

This will start:

• frontend
• backend
• MongoDB (if configured)

---

🔐 Login

Use the admin credentials from backend .env.

Example:

Email: admin@example.com
Password: admin123

---

🧪 Example Queries

Try natural language queries like:

Show all users from India

Find orders above 500 placed last month

List the top 10 products by sales

Show customers who signed up this year

NeuroQuery will:

1. Generate a MongoDB query
2. Explain what it does
3. Validate safety
4. Execute the query
5. Return results

---

📊 Result Views

Results can be displayed as:

Table format
JSON format
CSV export

Pagination ensures large datasets are handled efficiently.

---

🗂 Query History

All queries are logged with metadata:

• natural language input
• generated MongoDB query
• execution time
• user
• timestamp

This supports auditing and debugging.

---

🧰 Troubleshooting

Ollama Not Running

If AI queries fail:

Ensure Ollama is running:

ollama run llama3.1:8b

Check configuration:

OLLAMA_BASE_URL=http://localhost:11434

---

Port Already in Use

Change backend port in .env:

PORT=8081

Update frontend:

VITE_API_URL=http://localhost:8081

---

MongoDB Connection Issues

Verify MongoDB is running:

mongodb://localhost:27017

Check:

MONGODB_URI
MONGODB_DB

---

📈 Future Improvements

Voice queries
Multi-database support
Query visualization
Auto index creation
Query performance dashboards

---

📜 License

MIT License

(Add LICENSE file if distributing publicly)

---

⭐ Contributing

Contributions are welcome.

Steps:

1. Fork the repository
2. Create a feature branch
3. Submit a pull request

---

👨‍💻 Author

NeuroQuery
AI-powered database interface for modern data workflows.

If you find this project useful, consider starring the repository ⭐