GH-2979 Allow query explanation via REST API (#5312)

Author: hmottestad

core/http/protocol/src/main/java/org/eclipse/rdf4j/http/protocol/Protocol.java

@@ -166,6 +166,8 @@ public enum TIMEOUT {
 
 	public static final String OFFSET_PARAM_NAME = "offset";
 
+	public static final String EXPLAIN_PARAM_NAME = "explain";
+
 	/**
 	 * Parameter name for the query language parameter.
 	 */

site/static/documentation/reference/rest-api/rdf4j-openapi.yaml

@@ -187,6 +187,7 @@ components:
           schema:
             type: string
             format: binary
+
   examples:
     SparqlXmlBindings:
       value: |
@@ -381,6 +382,22 @@ paths:
           description: Specifies the number of query solutions to skip. The value should be a positive integer. This parameter is cumulative with any OFFSET modifier in the supplied SPARQL query itself.
           schema:
             type: integer
+        - name: explain
+          in: query
+          required: false
+          description: |
+            The level of explanation to return. If specified, the server will return an explanation of the query execution plan. The value should be one of the following:
+            - `Unoptimized`: Simple parsed plan
+            - `Optimized`: Parsed and optimized plan, including cost estimation
+            - `Executed`: Plan as it was executed, including actual result size
+            - `Timed`: Executed plan with timing details for each node
+          schema:
+            type: string
+            enum:
+              - Unoptimized
+              - Optimized
+              - Executed
+              - Timed
       responses:
         '200':
           $ref: "#/components/responses/200SparqlResult"
@@ -449,7 +466,7 @@ paths:
         required: true
         $ref: "#/components/requestBodies/RdfData"
       responses:
-        '204': 
+        '204':
           description: created
 
   /repositories/{repositoryID}/statements:
@@ -829,8 +846,8 @@ paths:
               type: string
             example: http://www.example.com
       responses:
-          204:
-            description: The defined namespace was successfully set to the given prefix.
+        204:
+          description: The defined namespace was successfully set to the given prefix.
     delete:
       tags:
         - Namespaces
@@ -1126,24 +1143,24 @@ paths:
           description: No content
 
     delete:
-        tags:
-          - Transactions
-        summary: Abort a transaction
-        description: |
-          An active transaction can be aborted by means of a HTTP DELETE request on the transaction resource. This will execute a transaction rollback on the repository and will close the transaction. After executing a DELETE, further operations on the same transaction will result in an error.
-        parameters:
-          - name: repositoryID
-            in: path
-            required: true
-            description: The repository ID
-            schema:
-              type: string
-          - name: transactionID
-            in: path
-            required: true
-            schema:
-              type: string
-            description: The transaction ID
-        responses:
-          204:
-            description: Successfully aborted the defined transaction.
+      tags:
+        - Transactions
+      summary: Abort a transaction
+      description: |
+        An active transaction can be aborted by means of a HTTP DELETE request on the transaction resource. This will execute a transaction rollback on the repository and will close the transaction. After executing a DELETE, further operations on the same transaction will result in an error.
+      parameters:
+        - name: repositoryID
+          in: path
+          required: true
+          description: The repository ID
+          schema:
+            type: string
+        - name: transactionID
+          in: path
+          required: true
+          schema:
+            type: string
+          description: The transaction ID
+      responses:
+        204:
+          description: Successfully aborted the defined transaction.

tools/server-spring/src/main/java/org/eclipse/rdf4j/http/server/repository/ExplainQueryResultView.java

@@ -0,0 +1,64 @@
+/*******************************************************************************
+ * Copyright (c) 2025 Eclipse RDF4J contributors.
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Distribution License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *******************************************************************************/
+package org.eclipse.rdf4j.http.server.repository;
+
+import java.io.IOException;
+import java.io.PrintWriter;
+import java.util.Map;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+import org.apache.http.HttpStatus;
+import org.eclipse.rdf4j.http.protocol.Protocol;
+import org.eclipse.rdf4j.query.explanation.Explanation;
+
+public class ExplainQueryResultView extends QueryResultView {
+
+	private static final String MIME_PLAIN = "text/plain";
+	private static final String MIME_JSON = "application/json";
+
+	@Override
+	protected void renderInternal(
+			final Map model, final HttpServletRequest request, final HttpServletResponse response) throws IOException {
+
+		String mimeType = getRequestedMimeType(request);
+		Explanation explanation = (Explanation) model.get(QUERY_EXPLAIN_RESULT_KEY);
+
+		if (explanation == null) {
+			response.sendError(HttpServletResponse.SC_BAD_REQUEST, "No explanation result found.");
+			return;
+		}
+
+		response.setCharacterEncoding("UTF-8");
+		response.setStatus(HttpStatus.SC_OK);
+
+		try (PrintWriter writer = response.getWriter()) {
+			if (MIME_JSON.equals(mimeType)) {
+				response.setContentType(MIME_JSON);
+				writer.write(explanation.toJson());
+			} else if (MIME_PLAIN.equals(mimeType) || mimeType == null || mimeType.isEmpty()) {
+				response.setContentType(MIME_PLAIN);
+				writer.write(explanation.toString());
+			} else {
+				response.sendError(
+						HttpServletResponse.SC_BAD_REQUEST,
+						"Unsupported MIME type: " + mimeType + ". Must be either text/plain or application/json."
+				);
+			}
+		}
+	}
+
+	private String getRequestedMimeType(HttpServletRequest request) {
+		String mimeType = request.getParameter(Protocol.ACCEPT_PARAM_NAME);
+		return (mimeType != null) ? mimeType : request.getHeader("Accept");
+	}
+}

tools/server-spring/src/main/java/org/eclipse/rdf4j/http/server/repository/QueryResultView.java

@@ -40,6 +40,11 @@ public abstract class QueryResultView implements View {
 	 */
 	public static final String QUERY_RESULT_KEY = "queryResult";
 
+	/**
+	 * Key by which the query result explanation is stored in the model.
+	 */
+	public static final String QUERY_EXPLAIN_RESULT_KEY = "explainResult";
+
 	/**
 	 * Key by which the query result writer factory is stored in the model.
 	 */

tools/server-spring/src/main/java/org/eclipse/rdf4j/http/server/repository/handler/AbstractQueryRequestHandler.java

@@ -16,6 +16,7 @@
 import java.io.IOException;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Optional;
 
 import javax.servlet.http.HttpServletRequest;
 import javax.servlet.http.HttpServletResponse;
@@ -32,6 +33,7 @@
 import org.eclipse.rdf4j.query.Query;
 import org.eclipse.rdf4j.query.QueryEvaluationException;
 import org.eclipse.rdf4j.query.QueryInterruptedException;
+import org.eclipse.rdf4j.query.explanation.Explanation;
 import org.eclipse.rdf4j.repository.Repository;
 import org.eclipse.rdf4j.repository.RepositoryConnection;
 import org.slf4j.Logger;
@@ -54,8 +56,10 @@ public AbstractQueryRequestHandler(RepositoryResolver repositoryResolver) {
 	}
 
 	@Override
-	public ModelAndView handleQueryRequest(HttpServletRequest request, RequestMethod requestMethod,
-			HttpServletResponse response) throws HTTPException, IOException {
+	public ModelAndView handleQueryRequest(
+			HttpServletRequest request, RequestMethod requestMethod,
+			HttpServletResponse response
+	) throws HTTPException, IOException {
 
 		RepositoryConnection repositoryCon = null;
 		Object queryResponse = null;
@@ -74,11 +78,14 @@ public ModelAndView handleQueryRequest(HttpServletRequest request, RequestMethod
 			long limit = getLimit(request);
 			long offset = getOffset(request);
 			boolean distinct = isDistinct(request);
-
+			final Optional<Explanation.Level> explainLevel = getExplain(request);
 			try {
-				if (headersOnly) {
-					queryResponse = null;
-				} else {
+				if (!headersOnly) {
+					// explain param is present, return the query explanation
+					if (explainLevel.isPresent()) {
+						final Explanation explanation = explainQuery(query, explainLevel.get());
+						return getExplainQueryResponse(request, response, explanation);
+					}
 					queryResponse = evaluateQuery(query, limit, offset, distinct);
 				}
 
@@ -134,6 +141,14 @@ public ModelAndView handleQueryRequest(HttpServletRequest request, RequestMethod
 
 	}
 
+	protected Explanation explainQuery(final Query query, final Explanation.Level explainLevel)
+			throws ServerHTTPException {
+		throw new ServerHTTPException("unimplemented explainQuery feature");
+	}
+
+	protected abstract ModelAndView getExplainQueryResponse(
+			final HttpServletRequest request, final HttpServletResponse response, final Explanation explanation);
+
 	abstract protected Object evaluateQuery(Query query, long limit, long offset, boolean distinct)
 			throws ClientHTTPException;
 
@@ -147,9 +162,11 @@ abstract protected String getQueryString(HttpServletRequest request, RequestMeth
 	abstract protected Query getQuery(HttpServletRequest request, RepositoryConnection repositoryCon,
 			String queryString) throws IOException, HTTPException;
 
-	protected ModelAndView getModelAndView(HttpServletRequest request, HttpServletResponse response,
+	protected ModelAndView getModelAndView(
+			HttpServletRequest request, HttpServletResponse response,
 			boolean headersOnly, RepositoryConnection repositoryCon, View view, Object queryResult,
-			FileFormatServiceRegistry<? extends FileFormat, ?> registry) throws ClientHTTPException {
+			FileFormatServiceRegistry<? extends FileFormat, ?> registry
+	) throws ClientHTTPException {
 		Map<String, Object> model = new HashMap<>();
 		model.put(QueryResultView.FILENAME_HINT_KEY, "query-result");
 		model.put(QueryResultView.QUERY_RESULT_KEY, queryResult);
@@ -172,6 +189,19 @@ protected long getLimit(HttpServletRequest request) throws ClientHTTPException {
 		return getParam(request, Protocol.LIMIT_PARAM_NAME, 0L, Long.TYPE);
 	}
 
+	protected Optional<Explanation.Level> getExplain(HttpServletRequest request) throws ClientHTTPException {
+		final String explainString = request.getParameter(Protocol.EXPLAIN_PARAM_NAME);
+		if (explainString == null) {
+			return Optional.empty();
+		}
+		try {
+			final Explanation.Level level = Explanation.Level.valueOf(explainString);
+			return Optional.of(level);
+		} catch (final IllegalArgumentException e) {
+			throw new ClientHTTPException("Invalid explanation level: " + explainString, e);
+		}
+	}
+
 	<T> T getParam(HttpServletRequest request, String distinctParamName, T defaultValue, Class<T> clazz)
 			throws ClientHTTPException {
 		if (clazz == Boolean.TYPE) {

tools/server-spring/src/main/java/org/eclipse/rdf4j/http/server/repository/handler/DefaultQueryRequestHandler.java

@@ -24,8 +24,11 @@
 
 import java.io.IOException;
 import java.util.Enumeration;
+import java.util.HashMap;
+import java.util.Map;
 
 import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
 
 import org.apache.commons.io.IOUtils;
 import org.apache.http.HttpStatus;
@@ -38,9 +41,7 @@
 import org.eclipse.rdf4j.http.server.ClientHTTPException;
 import org.eclipse.rdf4j.http.server.HTTPException;
 import org.eclipse.rdf4j.http.server.ProtocolUtil;
-import org.eclipse.rdf4j.http.server.repository.BooleanQueryResultView;
-import org.eclipse.rdf4j.http.server.repository.GraphQueryResultView;
-import org.eclipse.rdf4j.http.server.repository.TupleQueryResultView;
+import org.eclipse.rdf4j.http.server.repository.*;
 import org.eclipse.rdf4j.http.server.repository.resolver.RepositoryResolver;
 import org.eclipse.rdf4j.model.IRI;
 import org.eclipse.rdf4j.model.Value;
@@ -56,6 +57,7 @@
 import org.eclipse.rdf4j.query.TupleQuery;
 import org.eclipse.rdf4j.query.TupleQueryResult;
 import org.eclipse.rdf4j.query.UnsupportedQueryLanguageException;
+import org.eclipse.rdf4j.query.explanation.Explanation;
 import org.eclipse.rdf4j.query.impl.SimpleDataset;
 import org.eclipse.rdf4j.query.resultio.BooleanQueryResultWriterRegistry;
 import org.eclipse.rdf4j.query.resultio.TupleQueryResultWriterRegistry;
@@ -65,6 +67,7 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.web.bind.annotation.RequestMethod;
+import org.springframework.web.servlet.ModelAndView;
 import org.springframework.web.servlet.View;
 
 public class DefaultQueryRequestHandler extends AbstractQueryRequestHandler {
@@ -75,6 +78,22 @@ public DefaultQueryRequestHandler(RepositoryResolver repositoryResolver) {
 		super(repositoryResolver);
 	}
 
+	@Override
+	protected Explanation explainQuery(final Query query, final Explanation.Level level) {
+		return query.explain(level);
+	}
+
+	@Override
+	protected ModelAndView getExplainQueryResponse(
+			final HttpServletRequest request, final HttpServletResponse response,
+			final Explanation explanation
+	) {
+		Map<String, Object> model = new HashMap<>();
+		model.put(QueryResultView.FILENAME_HINT_KEY, "query-result");
+		model.put(QueryResultView.QUERY_EXPLAIN_RESULT_KEY, explanation);
+		return new ModelAndView(new ExplainQueryResultView(), model);
+	}
+
 	@Override
 	protected Object evaluateQuery(Query query, long limit, long offset, boolean distinct) throws ClientHTTPException {
 		if (query instanceof TupleQuery) {