Improve construct query result to triples by marvin7122 · Pull Request #2654 · ad-freiburg/qlever

marvin7122 · 2026-01-21T12:21:52Z

Improvement of perfomance of CONSTRUCT query export runtimes of about 70%:
This PR improves the perfomance of CONSTRUCT query result serialization through 4 main optimizations:

id-to-string caching: A StableLRUCache memoizes id to string conversions, avoiding redundant vocabulary lookups when the same entity appears multiple times across multiple rows of the result-table.
Column-Oriented batch processing: Rows of the result-table are processed in batches (default batch size 64, i did not get "stable" results when trying to empirically find out which batch size was best, more on that below). This allows us to fetch the Values for the variables for one variable after each other across the rows in the batch (first fetch the values for variable ?x across rows 0 to 63, then fetch the values for variable ?y for rows 0 to 63 and so on). Since IdTable uses a column-major memory layout, reading all Ids for a variable across different result-table rows creates sequential memory access patterns that benefit from CPU prefetching.
direct formatting: For streaming output, the generator now yields formatted strings directly, eliminating intermediate StringTriple object allocations.
Constants (iris, Literals) and the column indices corresponding to the variables in the IdTable are computed once, before we iterate over any result-table-rows.

marvin7122 · 2026-01-21T13:56:52Z

Comment regarding commit with hash 62b0ec9

Precomputing the constants (IRIs, Literals) that are present in the construct-query template and then skipping them when evaluating the construct-template triple patterns based on a particular row of the result table yields an improvement of about 23% (as I have measured it, in comparison to commit caed761, both binaries built in Release mode) on the following query on the dblp index:

PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>

CONSTRUCT {
  ?s rdf:type ?type .
  ?s <http://example.org/active> "yes" .
  ?s ?p ?o .
}
WHERE {
  ?s ?p ?o .
}
LIMIT 1000000

…ved readability

…readable

…ull request ad-freiburg#2298

# Conflicts: # CMakeLists.txt

… each row of the result table (result of the WHERE clause), and thus treat them in the caching mechanism in the same way that we treat Variables

…glevel>=DEBUG

…stats in the server log (even when I build for the Debug Release type),I dont get why

…a CONSTRUCT-query, move the cache stats computation and report to after we have iterated over all rows in the result table for the WHERE-clause

…ryExporter cache, to check if this is the reason why the statistics are not written to the server log

…s of the constructQueryExporter are still written to the server log

…variableHits_; now returns variableMisses_ as it should be

…xists

…, Iri, Literal classes and put them into the ConstructQueryEvaluator class. copy helper functions from ExportQueryExecutionTrees to this class aswell. Those still need to be refactored

…ueryCache for Iri's and Literals, since their values should be the same across all rows of the WHERE-clause-result-table and across all triples in the CONSTRUCT-query clause.

…he.h

…different types of Graphterms in ConstructQueryEvaluator instead of the classes themselves

marvin7122 · 2026-02-02T13:36:23Z

According to my measurements, with the binary for commit cfddafe built in Release mode, running the attached SELECT query takes about 1750ms, while running the attached CONSTRUCT query takes 1100ms. Thus, the
CONSTRUCT exporter is now even faster than the SELECT query export.

Settings for the benchmark:

=== Query Comparison Configuration ===
Date: Mon Feb  2 02:24:24 PM CET 2026
Server binary: /home/userNoPriv/code/qlever/qlever-code/build/qlever-server
Fresh server instance: YES (per query)

Query A: SELECT
  Accept header: text/csv
  Response extension: csv
  Query: SELECT ?s ?p ?o WHERE { ?s ?p ?o . } LIMIT 1000000

Query B: CONSTRUCT
  Accept header: text/csv
  Response extension: csv
  Query: CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o } LIMIT 1000000

Warmup runs: 1
Measured runs: 4
Query timeout: 3600s

Responses saved in: /home/userNoPriv/code/qlever/profiles_benchmarks/benchmarks/compare_queries_20260202-142424/responses

results:

Query A (SELECT): 1756 ms (avg) wall-clock time from sending the request to receiving the whole response.
Query B (CONSTRUCT):  1174 ms (avg) wall-clock time [...].
Time delta: CONSTRUCT is 582ms faster than SELECT (66%)
=== Memory (RSS) ===
--------------------------------------------------------------------------------
SELECT         : avg peak    217 MB, max peak    218 MB, avg delta +117 MB
CONSTRUCT      : avg peak    232 MB, max peak    234 MB, avg delta +131 MB
--------------------------------------------------------------------------------
Memory delta: CONSTRUCT uses +14MB more than SELECT.

marvin7122 · 2026-02-02T14:16:52Z

Perfomance comparison of the CONSTRUT query exporter:
commit cca37689 (HEAD of the master branch as of writing) vs commit cfddafeb (HEAD of improveConstructQueryResultToTriples):
Both binaries built in Release mode, query asked on dlblp index.

query:

CONSTRUCT {
  ?s ?p ?o .
}
WHERE {
  ?s ?p ?o .
}
LIMIT 1000000

results:

======================================================================
QLever Benchmark Analysis Report
======================================================================
Analysis date: 2026-02-02 15:12:39
Version 1: masterBranchHEAD
Version 2: myFeatureBranchHEAD
Results directory: /home/userNoPriv/code/qlever/profiles_benchmarks/benchmarks/benchmark_20260202-150727

SUMMARY STATISTICS
----------------------------------------------------------------------
Statistic                 masterBranchHEAD     myFeatureBranchHEAD  Difference     
----------------------------------------------------------------------
Mean Response Time        3607ms               1070ms               -70.3%         
Median Response Time      3597ms               1068ms               -70.3%             

Test Used: Student's t-test
Sample Sizes: 10 vs 10
Test Statistic: t = 206.818

marvin7122 · 2026-02-02T14:18:57Z

I have benchmarked and analyzed many more queries. Also, i did some empirical tests for setting the size of the batchsize, but I do not want to spam this PR with too many comments right now.

codecov · 2026-02-02T18:42:35Z

Codecov Report

❌ Patch coverage is 89.87342% with 32 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.58%. Comparing base (cca3768) to head (a4d83f8).
⚠️ Report is 2 commits behind head on master.

Files with missing lines	Patch %	Lines
src/engine/ConstructTripleGenerator.cpp	84.50%	8 Missing and 3 partials ⚠️
src/engine/ConstructIdCache.cpp	12.50%	6 Missing and 1 partial ⚠️
src/engine/ConstructBatchProcessor.cpp	96.59%	2 Missing and 4 partials ⚠️
src/engine/ConstructIdCache.h	37.50%	5 Missing ⚠️
src/engine/ConstructQueryEvaluator.cpp	92.30%	1 Missing and 1 partial ⚠️
src/engine/ExportQueryExecutionTrees.cpp	94.11%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2654      +/-   ##
==========================================
- Coverage   91.60%   91.58%   -0.02%     
==========================================
  Files         483      487       +4     
  Lines       41360    41607     +247     
  Branches     5493     5540      +47     
==========================================
+ Hits        37886    38104     +218     
- Misses       1897     1919      +22     
- Partials     1577     1584       +7

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

…anced readability

…StringTriples method

joka921

Some initial comments.
There is a lot of good stuff in there,
but we can have a discussion about the details in person.

joka921 · 2026-02-03T07:35:38Z

src/util/StableLruCache.h

+template <typename K, typename V>
+class StableLRUCache {
+ public:
+  explicit StableLRUCache(size_t capacity) : capacity_{capacity} {
+    AD_CONTRACT_CHECK(capacity > 0);


I think there are simpler ways to do this (e.g. using a node-based hashmap, or wrapping the values in a unique_ptr (relying on the reserve/capcity behavior is a little bit wonky).
But as the interface of this cache is simple, we can iterate that later on once we have identified the impact of the different tradeoff.

TLDR: If affordable, I would like to have this as "the ordinary LruCache we already have, but configured with different template parameters to reduce code bloat".

joka921 · 2026-02-03T07:36:44Z

src/engine/ExportQueryExecutionTrees.h


-// Class for computing the result of an already parsed and planned query and
-// exporting it in different formats (TSV, CSV, Turtle, JSON, Binary).
-//


don't delete comments?

joka921 · 2026-02-03T07:37:15Z

src/engine/ExportQueryExecutionTrees.h

-  //
-  // Blocks, where all rows are before OFFSET, are requested (and hence
-  // computed), but skipped.
-  //
-  // Blocks, where at least one row is after OFFSET but before the effective
-  // export limit (minimum of the LIMIT and the value of the `send` parameter),
-  // are requested and yielded (together with the corresponding `LocalVocab`
-  // and the range from that `IdTable` that belongs to the result).
-  //
-  // Blocks after the effective export limit until the LIMIT are requested, and
-  // counted towards the `totalResultSize`, but not yielded.
-  //
-  // Blocks after the LIMIT are not even requested.


don't delete comments, but move them alognside the declaration?

joka921 · 2026-02-03T07:39:01Z

src/engine/ExportQueryExecutionTrees.cpp

+constexpr ConstructOutputFormat mediaTypeToConstructFormat(
+    ad_utility::MediaType mediaType) {
+  using enum ad_utility::MediaType;
+  using enum ConstructOutputFormat;
+  switch (mediaType) {
+    case turtle:
+      return TURTLE;
+    case csv:
+      return CSV;
+    case tsv:
+      return TSV;
+    default:
+      // This should never be reached for valid CONSTRUCT formats
+      return TURTLE;
+  }


I don't see why we can't use the `MediaType directly? that transformation doesn't seem to do much:)

joka921 · 2026-02-03T07:40:37Z

src/engine/ExportQueryExecutionTrees.cpp

+  static_assert(
+      format == MediaType::octetStream || format == MediaType::csv ||
+      format == MediaType::tsv || format == MediaType::sparqlXml ||
+      format == MediaType::sparqlJson || format == MediaType::qleverJson ||
+      format == MediaType::binaryQleverExport || format == MediaType::turtle);


can be simplified (set up a constexpr array of the supported media types (including a using enum etc.), and then use ad_utility::contains in the assertion (opportunity to improve).

joka921 · 2026-02-03T08:06:29Z

src/engine/ConstructTripleGenerator.h

+  // TODO<ms2144>: Use more principled approach: maybe compute batch size
+  // dynamically based on the number of variables and available cache size,
+  // rather than using a fixed value. And also monitor how much of the L2 cache
+  // is used when a batch is being processed.


Yes, and also:
Is 64 enough s.t. it is not the reading from the vocabulary that is still the bottle neck (I am very interested in the perf graphs / flame graphs).

joka921 · 2026-02-03T08:11:29Z

src/engine/ConstructTripleGenerator.h

+    // Get value for a specific blank node at a row in the batch
+    const std::string& getBlankNodeValue(size_t blankNodeIdx,
+                                         size_t rowInBatch) const {
+      return blankNodeValues_[blankNodeIdx][rowInBatch];
+    }


This code dublication can be abstracted away in a 2D-Array class etc. (that stores the vector + the get function + is templated.

joka921 · 2026-02-03T08:17:31Z

src/engine/ConstructTripleGenerator.h

+
+  // Ordered list of `BlankNodes` with precomputed format info for evaluation
+  // (index corresponds to cache index)
+  std::vector<BlankNodeFormatInfo> blankNodesToEvaluate_;


The ideas all are nice,
I currently think the module is definnitely too long.
For example all the caching + statistics can be seaprate,

and the analysis of the template can also be in a separate module that is then just used by the evaluator.

joka921 · 2026-02-03T08:19:21Z

src/engine/ConstructTripleGenerator.cpp

+namespace {
+// Parse QLEVER_CONSTRUCT_BATCH_SIZE environment variable.
+// Returns the configured value if valid, or DEFAULT_BATCH_SIZE otherwise.
+size_t parseBatchSizeFromEnv() {
+  const char* envVal = std::getenv("QLEVER_CONSTRUCT_BATCH_SIZE");
+  if (envVal == nullptr) {
+    AD_LOG_INFO << "CONSTRUCT batch size: "
+                << ConstructTripleGenerator::DEFAULT_BATCH_SIZE
+                << " (default)\n";
+    return ConstructTripleGenerator::DEFAULT_BATCH_SIZE;
+  }
+  try {
+    size_t val = std::stoull(envVal);
+    if (val > 0) {
+      AD_LOG_INFO << "CONSTRUCT batch size from environment: " << val << "\n";
+      return val;
+    }
+    AD_LOG_WARN << "QLEVER_CONSTRUCT_BATCH_SIZE must be > 0, got: " << envVal
+                << ", using default: "
+                << ConstructTripleGenerator::DEFAULT_BATCH_SIZE << "\n";
+  } catch (const std::exception& e) {
+    AD_LOG_WARN << "Invalid QLEVER_CONSTRUCT_BATCH_SIZE value: " << envVal
+                << " (" << e.what() << "), using default: "
+                << ConstructTripleGenerator::DEFAULT_BATCH_SIZE << "\n";
+  }
+  return ConstructTripleGenerator::DEFAULT_BATCH_SIZE;
+}
+}  // namespace


If you want this, use an established mechanism like qlevers runtime parameters etc.
This is surprising to see somewhere in a cpp file :))

joka921 · 2026-02-03T08:21:57Z

src/engine/ConstructTripleGenerator.cpp

+  std::optional<BatchEvaluationCache> batchCache_;
+  std::vector<const std::string*> variableStrings_;
+};
+


This code is very long, maybe first clean up:)

…tility::Mediatype`, and therefore introduces complexity without a benefit.

…red_ptr<string>.

…nerator

…ing of the code

sparql-conformance · 2026-02-04T18:29:43Z

Overview

Number of Tests	Passed ✅	Intended ✅	Failed ❌	Not tested
547	449	73	25	0

Conformance check passed ✅

No test result changes.

Details: https://qlever.dev/sparql-conformance-ui?cur=a4d83f81bf2641a825d457873206d6a234a936a7&prev=f35a290fc35e28fefdc9ac56139660fad14ab860

sonarqubecloud · 2026-02-04T19:42:33Z

Quality Gate passed

Issues
11 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

marvin7122 added 29 commits January 22, 2026 13:24

replace auto with explicit types, order function parameters for impro…

638b26d

…ved readability

applied improvements as suggested by clang-tidy

9031950

add comments with notes for myself and refactor code to make it more …

494ae39

…readable

reverse function constructQueryResultToTriples to state from before p…

88f90d3

…ull request ad-freiburg#2298

add caching mechanism for construct query exporter

72042d3

# Conflicts: # CMakeLists.txt

convert CacheStats from struct to class and add apropriate functions

ce4ccc3

remove logging of cache stats

b032418

write construtQueryResultToTriples cache statistics to AD_LOG_DEBUG

de914dc

add ConstructQueryCache::evaluateWithCacheImpl<BlankNode>

60391dc

fix caching for BlankNodes: we need to clear the blankNodeCache after…

744c019

… each row of the result table (result of the WHERE clause), and thus treat them in the caching mechanism in the same way that we treat Variables

only compute logging statistics for ConstructQueryExportCache when Lo…

a4b3233

…glevel>=DEBUG

write to AD_LOG_INFO instead to AD_LOG_DEBUG, because I dont see the …

9d0fcc6

…stats in the server log (even when I build for the Debug Release type),I dont get why

bugfix: do not compute stats after every row of the result table for …

215b8ac

…a CONSTRUCT-query, move the cache stats computation and report to after we have iterated over all rows in the result table for the WHERE-clause

remove if clause for logging of cache statistics for the constructQue…

a458d6f

…ryExporter cache, to check if this is the reason why the statistics are not written to the server log

fix logging, such that, when the function exits early, the cache stat…

0ebd5d8

…s of the constructQueryExporter are still written to the server log

write to AD_LOG_INFO instead of to AD_LOG_DEBUG

e853087

fix formatting of construct query cache logger

e8e6ce1

fix bug: variableMisses() function in ConstructQueryCache.h returned …

118fce3

…variableHits_; now returns variableMisses_ as it should be

fix bug: forgot to delete line referencing local var that no longer e…

951ff10

…xists

decouple implementation of evaluate function from Variable, BlankNode…

a25da20

…, Iri, Literal classes and put them into the ConstructQueryEvaluator class. copy helper functions from ExportQueryExecutionTrees to this class aswell. Those still need to be refactored

do not use the context for creating the key hashes for the constructQ…

e6f1043

…ueryCache for Iri's and Literals, since their values should be the same across all rows of the WHERE-clause-result-table and across all triples in the CONSTRUCT-query clause.

fix compilation failure

d6ca5c7

fix typo: clearRowCache was accidentally defined in ConstructQueryCac…

843788e

…he.h

remove function declaration of function which does not exist anymore

7984636

fix comments

67889e0

remove unused function

1afbce9

apply clang formatter pre-commit hook

ae6de47

remove [nodiscard] from const methods of class

e5d02a6

remove old functions that are no longer needed since we evaluate the …

0b9d6b5

…different types of Graphterms in ConstructQueryEvaluator instead of the classes themselves

marvin7122 closed this Feb 2, 2026

marvin7122 reopened this Feb 2, 2026

marvin7122 force-pushed the improveConstructQueryResultToTriples branch from 544b1d0 to 4e5c6e2 Compare February 2, 2026 11:01

simplify comments

932da72

marvin7122 force-pushed the improveConstructQueryResultToTriples branch from 4e5c6e2 to 932da72 Compare February 2, 2026 12:19

marvin7122 added 3 commits February 2, 2026 13:22

merge upstream/master

65fdee6

remove dead code, rewrite comments

241848c

remove deprecated ConstructQueryCache

cfddafe

marvin7122 added 2 commits February 2, 2026 17:13

code quality improvements

b4f528d

fix typo

eee51de

marvin7122 added 5 commits February 2, 2026 22:32

Extract init-captures into local variables before the lambda, for enh…

36a623d

…anced readability

Improve comments

936e373

Fix SonarQube code smell: extract 29-line lambda into processBatchFor…

572f19b

…StringTriples method

add comment back in, which was deleted by accident

d9fb287

add another comment back in

860c631

joka921 reviewed Feb 3, 2026

View reviewed changes

marvin7122 added 8 commits February 3, 2026 14:08

Remove ConstructOutputFormatsince it is just a wrapper around `ad_u…

9ff9736

…tility::Mediatype`, and therefore introduces complexity without a benefit.

Replace raw pointers with owned strings in BatchEvaluationCache

4de2b7e

Do not populate BatchEvaluationCache with string objects but with sha…

d118a17

…red_ptr<string>.

decouple batch processing of result-table rows from ConstructTripleGe…

80fa8b7

…nerator

small refactor: rename some methods and some types to ease understand…

1b05b70

…ing of the code

Remove variableStrings indirection in batch processing

1b20b67

Move all batch evaluation logic to ConstructBatchProcessor

9a89ee0

fix comment

a4d83f8

Conversation

marvin7122 commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marvin7122 commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marvin7122 commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marvin7122 commented Feb 2, 2026

Uh oh!

marvin7122 commented Feb 2, 2026

Uh oh!

codecov bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

joka921 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sparql-conformance bot commented Feb 4, 2026

Overview

Conformance check passed ✅

Uh oh!

sonarqubecloud bot commented Feb 4, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

marvin7122 commented Jan 21, 2026 •

edited

Loading

marvin7122 commented Jan 21, 2026 •

edited

Loading

marvin7122 commented Feb 2, 2026 •

edited

Loading

codecov bot commented Feb 2, 2026 •

edited

Loading