inovexis/qtt repository overview

⁠Query Templating Tool (QTT)

Query Templating Tool (QTT) is a microservice platform that translates domain-specific search requests into optimized SPARQL queries for graph database systems. It acts as a middleware layer between your applications and your knowledge graph, simplifying data access through templated queries.

⁠How It Works

HTTP Request + Freemarker Template → SPARQL Query → Graph Studio Backend → JSON-LD Results

Example Flow:

1. Your application sends a simple JSON request:

{
  "search_type": "email",
  "from": "[email protected]",
  "limit": 500
}

1. QTT uses a Freemarker template to generate an optimized SPARQL query
2. The query executes against your Graph Studio graph database
3. Results are streamed back as JSON-LD

⁠Key Features

• Template-Based Queries: Write SPARQL queries once as Freemarker templates, reuse with different parameters
• Dynamic Route Creation: Create, modify, and deploy query endpoints without code changes
• Multiple Database Backends: Supports Derby (embedded), PostgreSQL, and SQL Server for metadata/route persistence
• Real-Time Metrics: Built-in performance monitoring and route analytics
• Health Monitoring: Automatic datasource health checks with configurable failure handling
• Query Result Caching: Optional Redis-backed caching layer to reduce database load and improve response times
• AI-Powered Assistance: Optional SPARQi assistant helps develop SPARQL templates using LLMs
• Rich Web UI: Angular-based interface for managing datasources, routes, and monitoring performance
• RESTful API: Complete programmatic access to all features
• OSGi Runtime: Built on Apache Karaf for modular, hot-deployable components

⁠Use Cases

• Simplified Knowledge Graph Access: Hide SPARQL complexity from frontend developers
• Multi-Tenant Graph Queries: Route different clients to different graph layers
• Query Performance Optimization: Centralized template management and caching
• Graph Data API Gateway: Single endpoint for all graph database interactions
• Semantic Search Services: Build search APIs backed by ontology-driven queries

Runtime Architecture:

The application runs in Apache Karaf 4.4.1 and provides two separate HTTP applications:

1. JAX-RS Application (Port 8080 - HTTP)

   • Static CRUD endpoints for routes, datasources, layers
   • SPARQi AI assistant API
   • Metrics and settings endpoints

2. Camel Jetty Application (Port 8888 - HTTP)

   • Dynamically created query endpoints based on database route definitions
   • Endpoint pattern: http://localhost:8888/{route-id}?param=value

⁠Quick Start

The fastest way to get QTT running is using the official Docker image:

# Pull the image
docker pull docker.io/inovexis/qtt:latest

# Run the container
docker run -d \
  --name qtt \
  -p 8080:8080 \
  -p 8888:8888 \
  docker.io/inovexis/qtt:latest

⁠Documentation

Visit GitHub⁠

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

Copyright (c) 2025 RealmOne