A natural language to SQL query converter built with React and Tailwind CSS, powered by AI models to transform plain English questions into optimized SQL queries.
- Schema Upload: Upload database schemas in CSV, SQL, or JSON format
- Natural Language Processing: Ask questions in plain English
- SQL Generation: Automatically generate optimized SQL queries
- Modern UI: Beautiful, responsive interface built with Tailwind CSS
- Real-time Feedback: Instant query generation with explanations
- Database Connection: Direct connection to PostgreSQL databases
- Data Analysis: Interactive data visualization and analysis tools
- Node.js (v18 or higher)
- npm or yarn
- PostgreSQL database (for direct connections)
- Python 3.8+ (for backend API)
- Clone and setup the backend API:
# The backend should be running on http://localhost:8000
# Ensure the following endpoints are available:
# - POST /generate-sql
# - POST /connections
# - POST /generate-chart
# - GET /health- Install Python dependencies:
cd backend # Navigate to your backend directory
pip install -r requirements.txt- Start the backend server:
python main.py # or your backend startup command- Clone the repository:
git clone <repository-url>
cd QueryCatalyst- Install dependencies:
npm install- Configure environment variables:
# Create .env file if needed
REACT_APP_API_BASE_URL=http://localhost:8000- Start the development server:
npm start- Open http://localhost:3000 in your browser
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ React Frontend│ │ Backend API │ │ PostgreSQL │
│ │ │ │ │ Database │
│ - Schema Upload │◄──►│ - SQL Generation│◄──►│ - Data Storage │
│ - Query Input │ │ - Chart Gen. │ │ - Schema Info │
│ - Data Analysis │ │ - DB Connection │ │ - Query Exec. │
└─────────────────┘ └─────────────────┘ └─────────────────┘
- Component-Based Structure: Modular React components with clear separation of concerns
- Context API: Global state management using React Context for data persistence
- Routing: Single-page application with React Router for navigation
- Responsive Design: Mobile-first approach using Tailwind CSS
- Schema Input: User uploads schema or connects to database
- Query Processing: Natural language query sent to backend API
- SQL Generation: AI model generates SQL from natural language
- Execution: SQL executed against database (if connected)
- Results Display: Data presented in interactive tables and charts
- Natural Language to SQL: Large Language Model (LLM) for query understanding and SQL generation
- Chart Generation: AI-powered chart type selection and visualization generation
- Query Optimization: Model-based SQL query optimization and validation
- Schema Understanding: Parses and understands database schemas
- Query Intent Recognition: Converts natural language to SQL intent
- SQL Generation: Produces syntactically correct SQL queries
- Error Handling: Provides meaningful error messages and suggestions
- Language Support: Currently optimized for English queries
- Complex Queries: May struggle with highly complex nested queries
- Schema Complexity: Performance may degrade with very large schemas
- API Dependency: Frontend requires backend API to be running
- Database Support: Currently optimized for PostgreSQL, limited support for other databases
- Query Complexity: Very complex queries may not generate correctly
- Schema Size: Large schemas (>100 tables) may impact performance
- Database Credentials: Connection credentials stored in frontend state (consider encryption)
- SQL Injection: Generated SQL should be validated before execution
- Data Exposure: Sensitive data may be visible in query results
- API Security: Backend API lacks authentication/authorization
- Large Datasets: Querying very large datasets may cause timeouts
- Memory Usage: Large result sets may impact browser performance
- Network Latency: API calls may be slow on poor connections
- Caching: No built-in caching for repeated queries
- Schema Information: Database schemas are sent to AI services for processing
- Query Logs: User queries may be logged for model improvement
- Data Transmission: Sensitive data transmitted over network
- Upload Schema: Use the schema upload component to provide your database structure
- Connect Database: Alternatively, establish direct database connection
- Ask Questions: Type natural language questions about your data
- Get SQL: Receive generated SQL queries with explanations
- Execute Queries: Run queries directly against connected database
- Analyze Data: Use built-in tools for data visualization and analysis
- Frontend: React 18, React Router, Tailwind CSS
- Backend: Python FastAPI/Flask (assumed)
- Database: PostgreSQL with connection pooling
- AI/ML: Large Language Models for NLP and SQL generation
- Icons: Lucide React
- Build Tool: Create React App
src/
├── app/
│ ├── components/
│ │ ├── ui/ # Reusable UI components
│ │ ├── Header.js # Navigation header
│ │ ├── SchemaUpload.js
│ │ ├── SchemaDisplay.js
│ │ ├── QueryInput.js
│ │ ├── QueryResponse.js
│ │ ├── DataAnalysis.js
│ │ └── DatabaseConnection.js
│ ├── context/ # React Context for state management
│ ├── hooks/ # Custom React hooks
│ ├── App.js # Main application component
│ └── App.css
├── index.js # Application entry point
├── index.css # Global styles
└── mock.js # Mock data for development
- Mock Mode: Currently uses mock data for demonstration
- Production Ready: Designed to integrate with real AI services
- Extensible: Easy to add new features and components
- Testing: Unit tests and integration tests recommended
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Submit a pull request
This project is built for Hackathon 2025.
For issues and questions:
- Check the known limitations above
- Review the architecture overview
- Ensure all setup steps are completed
- Verify backend API is running and accessible