GH-5691 CLI for running and storing query explanations

Author: hmottestad

testsuites/benchmark/README.md

@@ -169,6 +169,14 @@ Every CLI run also prints:
 - `softLimitMillis` (currently `60000`)
 - whether stopping hit the soft-limit projection or max repeat-run cap
 
+### 8) Configure query timeout
+
+Set a per-query timeout in seconds (`0` disables timeout):
+
+```bash
+... -Dexec.args="--store memory --theme MEDICAL_RECORDS --query-index 0 --query-timeout-seconds 30"
+```
+
 ### 7) Run all themed queries across all themes for one store
 
 Memory store:

testsuites/benchmark/src/main/java/org/eclipse/rdf4j/benchmark/plan/QueryPlanSnapshotCli.java

@@ -35,6 +35,7 @@
 import org.eclipse.rdf4j.benchmark.common.plan.QueryPlanSnapshot;
 import org.eclipse.rdf4j.benchmark.rio.util.ThemeDataSetGenerator.Theme;
 import org.eclipse.rdf4j.common.annotation.Experimental;
+import org.eclipse.rdf4j.query.TupleQuery;
 import org.eclipse.rdf4j.queryrender.sparql.TupleExprIRRenderer;
 import org.eclipse.rdf4j.repository.sail.SailRepositoryConnection;
 
@@ -171,14 +172,16 @@ private void runSingleQueryCapture(QueryPlanSnapshotCliOptions options,
 		QueryExecutionVerification executionVerification;
 		try (SailRepositoryConnection connection = storeRuntime.repository.getConnection()) {
 			if (options.persist) {
-				snapshotPath = capture.captureAndWrite(context, () -> connection.prepareTupleQuery(queryText));
+				snapshotPath = capture.captureAndWrite(context,
+						() -> prepareTupleQuery(connection, queryText, options.queryTimeoutSeconds));
 				currentSnapshot = capture.readSnapshot(snapshotPath);
 				output.println("Snapshot written: " + snapshotPath.toAbsolutePath());
 			} else {
-				currentSnapshot = capture.capture(context, () -> connection.prepareTupleQuery(queryText));
+				currentSnapshot = capture.capture(context,
+						() -> prepareTupleQuery(connection, queryText, options.queryTimeoutSeconds));
 				output.println("Snapshot captured in-memory only (--persist=false).");
 			}
-			executionVerification = verifyRepeatedExecution(connection, queryText);
+			executionVerification = verifyRepeatedExecution(connection, queryText, options.queryTimeoutSeconds);
 		}
 
 		printResultsSection(options, queryId, queryText);
@@ -222,14 +225,17 @@ private void runAllThemeQueriesCapture(QueryPlanSnapshotCliOptions options,
 				QueryExecutionVerification executionVerification;
 				try (SailRepositoryConnection connection = storeRuntime.repository.getConnection()) {
 					if (options.persist) {
-						snapshotPath = capture.captureAndWrite(context, () -> connection.prepareTupleQuery(queryText));
+						snapshotPath = capture.captureAndWrite(context,
+								() -> prepareTupleQuery(connection, queryText, perQueryOptions.queryTimeoutSeconds));
 						currentSnapshot = capture.readSnapshot(snapshotPath);
 						output.println("Snapshot written: " + snapshotPath.toAbsolutePath());
 					} else {
-						currentSnapshot = capture.capture(context, () -> connection.prepareTupleQuery(queryText));
+						currentSnapshot = capture.capture(context,
+								() -> prepareTupleQuery(connection, queryText, perQueryOptions.queryTimeoutSeconds));
 						output.println("Snapshot captured in-memory only (--persist=false).");
 					}
-					executionVerification = verifyRepeatedExecution(connection, queryText);
+					executionVerification = verifyRepeatedExecution(connection, queryText,
+							perQueryOptions.queryTimeoutSeconds);
 				}
 
 				output.println();
@@ -589,6 +595,9 @@ private void promptAllRunOptions(QueryPlanSnapshotCliOptions options) throws IOE
 			options.diffMode = promptDiffMode(options.diffMode);
 		}
 		options.queryId = promptOptionalValue("Query id (blank keeps default/auto)", options.queryId);
+		options.queryTimeoutSeconds = promptOptionalNonNegativeInteger(
+				"Query timeout seconds (blank keeps current, 0 disables timeout)",
+				options.queryTimeoutSeconds);
 		if (options.outputDirectory == null) {
 			options.outputDirectory = promptOptionalPath("Output directory (blank uses default)");
 		}
@@ -641,6 +650,20 @@ private Path promptOptionalPath(String message) throws IOException {
 		return Path.of(raw.trim());
 	}
 
+	private Integer promptOptionalNonNegativeInteger(String message, Integer currentValue) throws IOException {
+		while (true) {
+			String raw = prompt(message);
+			if (raw.isBlank()) {
+				return currentValue;
+			}
+			try {
+				return QueryPlanSnapshotCliOptions.parseNonNegativeInteger(raw, message);
+			} catch (IllegalArgumentException e) {
+				output.println(e.getMessage());
+			}
+		}
+	}
+
 	private void promptForAssignments(String heading, Map<String, String> target) throws IOException {
 		output.println(heading);
 		while (true) {
@@ -807,6 +830,9 @@ private static QueryPlanCaptureContext createContext(QueryPlanSnapshotCliOptions
 				.addMetadata(QueryPlanCapture.metadataFromSystemProperties())
 				.featureFlagCollector(featureFlags)
 				.tupleExprRenderer(QueryPlanSnapshotCli::renderTupleExprWithIr);
+		if (options.queryTimeoutSeconds != null) {
+			contextBuilder.addMetadata("queryTimeoutSeconds", options.queryTimeoutSeconds.toString());
+		}
 
 		if (options.queryIndex != null && benchmarkQuery != null) {
 			contextBuilder.addMetadata("queryIndex", Integer.toString(options.queryIndex))
@@ -823,7 +849,8 @@ private static FeatureFlagCollector createFeatureFlagCollector(QueryPlanSnapshot
 				.addValue("cli.store", options.store.id)
 				.addValue("cli.theme", options.theme.name())
 				.addValue("cli.querySource", querySource)
-				.addValue("cli.persist", Boolean.toString(options.persist));
+				.addValue("cli.persist", Boolean.toString(options.persist))
+				.addValue("cli.queryTimeoutSeconds", formatQueryTimeoutSeconds(options.queryTimeoutSeconds));
 		if (options.queryIndex != null) {
 			featureFlags.addValue("cli.queryIndex", options.queryIndex.toString());
 		}
@@ -903,6 +930,22 @@ private static String normalizedOrNull(String value) {
 		return normalized.isEmpty() ? null : normalized;
 	}
 
+	private static String formatQueryTimeoutSeconds(Integer queryTimeoutSeconds) {
+		if (queryTimeoutSeconds == null || queryTimeoutSeconds == 0) {
+			return "<none>";
+		}
+		return queryTimeoutSeconds.toString();
+	}
+
+	private static TupleQuery prepareTupleQuery(SailRepositoryConnection connection, String queryText,
+			Integer queryTimeoutSeconds) {
+		TupleQuery tupleQuery = connection.prepareTupleQuery(queryText);
+		if (queryTimeoutSeconds != null && queryTimeoutSeconds > 0) {
+			tupleQuery.setMaxExecutionTime(queryTimeoutSeconds);
+		}
+		return tupleQuery;
+	}
+
 	private void printPrettyExplanations(QueryPlanSnapshot snapshot) {
 		Map<String, QueryPlanExplanation> explanations = snapshot.getExplanations();
 		if (explanations == null || explanations.isEmpty()) {
@@ -925,7 +968,8 @@ private void printResultsSection(QueryPlanSnapshotCliOptions options, String que
 		output.println("=== Results ===");
 		output.println("Original query:");
 		output.println(queryText.trim());
-		output.println("Store=" + options.store.id + ", Theme=" + options.theme + ", QueryId=" + queryId);
+		output.println("Store=" + options.store.id + ", Theme=" + options.theme + ", QueryId=" + queryId
+				+ ", QueryTimeoutSeconds=" + formatQueryTimeoutSeconds(options.queryTimeoutSeconds));
 	}
 
 	private void printExplanation(String levelKey, QueryPlanExplanation explanation) {
@@ -952,7 +996,8 @@ private void printExplanation(String levelKey, QueryPlanExplanation explanation)
 		}
 	}
 
-	private QueryExecutionVerification verifyRepeatedExecution(SailRepositoryConnection connection, String queryText) {
+	private QueryExecutionVerification verifyRepeatedExecution(SailRepositoryConnection connection, String queryText,
+			Integer queryTimeoutSeconds) {
 		long elapsedNanos = 0;
 		long stableResultCount = Long.MIN_VALUE;
 		int runs = 0;
@@ -971,7 +1016,10 @@ private QueryExecutionVerification verifyRepeatedExecution(SailRepositoryConnect
 			}
 
 			long startedAt = System.nanoTime();
-			long currentResultCount = connection.prepareTupleQuery(queryText).evaluate().stream().count();
+			long currentResultCount = prepareTupleQuery(connection, queryText, queryTimeoutSeconds)
+					.evaluate()
+					.stream()
+					.count();
 			long runNanos = Math.max(1L, System.nanoTime() - startedAt);
 			elapsedNanos += runNanos;
 			runs++;

testsuites/benchmark/src/main/java/org/eclipse/rdf4j/benchmark/plan/QueryPlanSnapshotCliOptions.java

@@ -47,6 +47,7 @@ final class QueryPlanSnapshotCliOptions {
 	Path outputDirectory;
 	String queryId;
 	Path lmdbDataDirectory;
+	Integer queryTimeoutSeconds;
 	final LinkedHashMap<String, String> systemProperties = new LinkedHashMap<>();
 	final LinkedHashMap<String, String> metadata = new LinkedHashMap<>();
 
@@ -75,6 +76,7 @@ QueryPlanSnapshotCliOptions copy() {
 		copy.outputDirectory = outputDirectory;
 		copy.queryId = queryId;
 		copy.lmdbDataDirectory = lmdbDataDirectory;
+		copy.queryTimeoutSeconds = queryTimeoutSeconds;
 		copy.systemProperties.putAll(systemProperties);
 		copy.metadata.putAll(metadata);
 		return copy;
@@ -172,6 +174,9 @@ static QueryPlanSnapshotCliOptions parseArgs(String[] args) {
 			case "--lmdb-data-dir":
 				options.lmdbDataDirectory = Path.of(requireValue(args, ++i, arg));
 				break;
+			case "--query-timeout-seconds":
+				options.queryTimeoutSeconds = parseNonNegativeInteger(requireValue(args, ++i, arg), arg);
+				break;
 			case "--property": {
 				Assignment assignment = parseAssignment(requireValue(args, ++i, arg), arg);
 				options.systemProperties.put(assignment.key, assignment.value);
@@ -336,6 +341,20 @@ private static boolean parseBoolean(String value, String optionName) {
 		throw new IllegalArgumentException("Invalid " + optionName + " value '" + value + "'. Use true or false.");
 	}
 
+	static int parseNonNegativeInteger(String value, String optionName) {
+		int parsed;
+		try {
+			parsed = Integer.parseInt(value.trim());
+		} catch (NumberFormatException e) {
+			throw new IllegalArgumentException("Invalid " + optionName + " value '" + value + "'. Use a whole number.",
+					e);
+		}
+		if (parsed < 0) {
+			throw new IllegalArgumentException("Invalid " + optionName + " value '" + value + "'. Must be >= 0.");
+		}
+		return parsed;
+	}
+
 	private static DiffMode parseDiffMode(String value, String optionName) {
 		String normalized = value.trim().toLowerCase(Locale.ROOT);
 		for (DiffMode mode : DiffMode.values()) {
@@ -421,6 +440,7 @@ static void printUsage(PrintStream output) {
 		output.println("  --all-theme-queries                  run all themed queries across all themes");
 		output.println("  --query <SPARQL>                     direct query text");
 		output.println("  --query-file <path>                  load query text from file");
+		output.println("  --query-timeout-seconds <int>=0      per-query max execution time (0 disables timeout)");
 		output.println("  --persist <true|false> | --no-persist");
 		output.println("  --compare-latest                     compare current run with latest prior run");
 		output.println();