Smart SPARQL Advisor

This repository contains the official implementation of Smart SPARQL Advisor, as presented in our PVLDB 2025 paper:
"Smart SPARQL Advisor: Guiding Users in Query Formulation with Performance Prediction"

The system integrates learned Query Performance Prediction (QPP) with large language model (LLM)–based query reformulation to assist users in crafting performant SPARQL queries over Knowledge Graphs.

🔍 Overview

Writing SPARQL queries is often an iterative and time-consuming process, especially by long-running query executions that may result in timeouts.
Smart SPARQL Advisor (SSA) addresses this challenge by:

• Predicting query runtimes prior to execution using a learned QPP model (PlanRGCN)
• Recommending runtime-efficient alternative queries via an LLM guided by learned query embeddings

📦 Repository Structure

SSA/
├── PlanRGCN/                    # PlanRGCN model for SPARQL Query Performance Prediction
│   ├── data/                    # Training datasets and query collections
│   ├── PlanRGCN/               # Core PlanRGCN implementation
│   ├── scripts/                # Utility scripts
│   └── README.md               # PlanRGCN-specific documentation
├── qpp_llm_frontend/           # Web application for Smart SPARQL Advisor
│   ├── backend/                # Python Flask backend
│   │   ├── app.py             # Main Flask application
│   │   ├── qpp_model_api.py   # QPP model API service
│   │   ├── ollama_client.py   # Ollama LLM client
│   │   └── streaming_utils.py # Streaming response utilities
│   ├── src/                   # React frontend source code
│   │   └── components/        # React components
│   └── package.json          # Node.js dependencies
├── q_recom/                  # Query recommendation system
│   └── prompt_gen.py         # Prompt templates for LLM-based reformulation
├── dockerfiles/             # Docker configurations
└── requirements.txt         # Python dependencies

🚀 Getting Started

Prerequisites

• Python 3.10+
• Node.js 16+ (for frontend)
• Ollama (for local LLM serving)
• A SPARQL endpoint (e.g., Virtuoso, Blazegraph)
• Trained PlanRGCN model and KG statistics

Installation

1. Clone the repository:

   git clone git@github.com:dkw-aau/SSA.git
   cd SSA

2. Install Python dependencies:

   pip install -r requirements.txt

3. Install Node.js dependencies:

   cd qpp_llm_frontend
   npm install
   cd ..

4. Install and setup Ollama:

   # Install Ollama
   curl -fsSL https://ollama.com/install.sh | sh
   
   # Pull required LLM models
   ollama pull llama3:8b
   ollama pull phi3:mini
   ollama pull qwen2.5:7b

Running the System

To run the Smart SPARQL Advisor system, you need to start three components in the following order:

1. Start Ollama server:

   ollama serve

2. Start the main Flask backend:

   python3 qpp_llm_frontend/backend/app.py

3. Start the QPP model API:

   python qpp_llm_frontend/backend/qpp_model_api.py

The web interface will be available at http://localhost:3000

Docker Deployment

Alternatively, you can use Docker to build and run the system:

docker build -t ssa:default -f dockerfiles/Dockerfile_nodejs .
# Add docker run commands as needed

🔧 Configuration

• SPARQL Endpoint: Configure your SPARQL endpoint URL in the web interface
• LLM Models: Available models are automatically detected from your Ollama installation
• QPP Model: Ensure the trained PlanRGCN model is available (see PlanRGCN/README.md)

📝 Usage

1. Open the web interface at http://localhost:3000
2. Enter your SPARQL endpoint URL
3. Select similarity function and LLM model
4. Input your SPARQL query
5. Click "Evaluate Query" to get:
   • Runtime prediction
   • Alternative query formulations (if needed)
   • Query execution results

📄 Citation

@article{mohanaraj2025ssa,
  title     = {Smart SPARQL Advisor: Guiding Users in Query Formulation with Performance Prediction},
  author    = {Abiram Mohanaraj and Matteo Lissandrini and Katja Hose},
  journal   = {PVLDB},
  volume    = {X},
  number    = {X},
  year      = {2025}
}