@jbr-experiment/largerdfbench 0.0.0-stage → 6.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,483 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || function (mod) {
19
+ if (mod && mod.__esModule) return mod;
20
+ var result = {};
21
+ if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
22
+ __setModuleDefault(result, mod);
23
+ return result;
24
+ };
25
+ Object.defineProperty(exports, "__esModule", { value: true });
26
+ exports.ExperimentLargeRdfBench = void 0;
27
+ const Path = __importStar(require("node:path"));
28
+ const fs = __importStar(require("fs-extra"));
29
+ const jbr_1 = require("jbr");
30
+ const n3_1 = require("n3");
31
+ const rdf_stores_1 = require("rdf-stores");
32
+ const sparql_benchmark_runner_1 = require("sparql-benchmark-runner");
33
+ const DatasetSampler_1 = require("./DatasetSampler");
34
+ const LineageComputer_1 = require("./LineageComputer");
35
+ const SampleValidator_1 = require("./SampleValidator");
36
+ const ZenodoArchive_1 = require("./ZenodoArchive");
37
+ /**
38
+ * An experiment instance for LargeRDFBench, a benchmark for SPARQL endpoint federation,
39
+ * using either its full datasets, or a sample of them over which the queries produce the same results.
40
+ */
41
+ class ExperimentLargeRdfBench {
42
+ /**
43
+ * @param zenodoRecord - The Zenodo record of the LargeRDFBench Interoperable Edition to download from.
44
+ * @param datasets - The datasets to include, by their name in the Zenodo record.
45
+ * @param queries - The queries to include, by their name in the Zenodo record.
46
+ * @param sample - If the datasets must be sampled. Otherwise, the full datasets are used, as HDT files.
47
+ * @param sampleSubjectRates - The fraction of subjects to sample per dataset, which defaults to 1. @range {json}
48
+ * @param sampleOtherTriplesRate - The fraction of the triples of sampled subjects that match no query pattern to
49
+ * keep. @range {double}
50
+ * @param sampleSeed - The seed for sampling.
51
+ * @param sampleValidate - If the queries must be validated to produce the same results over the sample as over the
52
+ * full data.
53
+ * @param generationQueryTimeout - The timeout in seconds of the queries over the full data during sampling.
54
+ * @param hookSparqlEndpoint - The SPARQL endpoint of the federation engine that is benchmarked.
55
+ * @param hookSparqlEndpointSources - The SPARQL endpoints of the datasets, which are started one by one.
56
+ * @param endpointUrl - The URL of the SPARQL endpoint of the federation engine.
57
+ * @param endpointUrlExternal - The URL to check if the SPARQL endpoint of the federation engine is available.
58
+ * @param sourceUrlsExternal - The URLs to check if each source is available before starting the next one.
59
+ * @param queryRunnerReplication - The number of replication runs.
60
+ * @param queryRunnerWarmupRounds - The number of warmup runs.
61
+ * @param queryRunnerRequestDelay - The delay between requests in milliseconds.
62
+ * @param queryRunnerEndpointAvailabilityCheckTimeout - The timeout of the availability check in milliseconds.
63
+ * @param queryRunnerUrlParams - URL parameters to pass to the SPARQL endpoint. @range {json}
64
+ * @param queryTimeoutFallback - A timeout in milliseconds for a single query, as fallback for the endpoint's timeout.
65
+ */
66
+ constructor(zenodoRecord, datasets, queries, sample, sampleSubjectRates, sampleOtherTriplesRate, sampleSeed, sampleValidate, generationQueryTimeout, hookSparqlEndpoint, hookSparqlEndpointSources, endpointUrl, endpointUrlExternal, sourceUrlsExternal, queryRunnerReplication, queryRunnerWarmupRounds, queryRunnerRequestDelay, queryRunnerEndpointAvailabilityCheckTimeout, queryRunnerUrlParams, queryTimeoutFallback) {
67
+ this.httpAvailabilityLatch = new jbr_1.HttpAvailabilityLatch();
68
+ this.zenodoRecord = zenodoRecord;
69
+ this.datasets = datasets;
70
+ this.queries = queries;
71
+ this.sample = sample;
72
+ this.sampleSubjectRates = sampleSubjectRates;
73
+ this.sampleOtherTriplesRate = sampleOtherTriplesRate;
74
+ this.sampleSeed = sampleSeed;
75
+ this.sampleValidate = sampleValidate;
76
+ this.generationQueryTimeout = generationQueryTimeout;
77
+ this.hookSparqlEndpoint = hookSparqlEndpoint;
78
+ this.hookSparqlEndpointSources = hookSparqlEndpointSources;
79
+ this.endpointUrl = endpointUrl;
80
+ this.endpointUrlExternal = endpointUrlExternal !== null && endpointUrlExternal !== void 0 ? endpointUrlExternal : endpointUrl;
81
+ this.sourceUrlsExternal = sourceUrlsExternal !== null && sourceUrlsExternal !== void 0 ? sourceUrlsExternal : [];
82
+ this.queryRunnerReplication = queryRunnerReplication;
83
+ this.queryRunnerWarmupRounds = queryRunnerWarmupRounds;
84
+ this.queryRunnerRequestDelay = queryRunnerRequestDelay;
85
+ this.queryRunnerEndpointAvailabilityCheckTimeout = queryRunnerEndpointAvailabilityCheckTimeout;
86
+ this.queryRunnerUrlParams = queryRunnerUrlParams;
87
+ this.queryTimeoutFallback = queryTimeoutFallback;
88
+ }
89
+ /**
90
+ * The paths of the generated files.
91
+ * @param generated The generated directory.
92
+ */
93
+ static getPaths(generated) {
94
+ return {
95
+ generated,
96
+ zenodoHdt: Path.join(generated, 'zenodo', 'hdt'),
97
+ zenodoQueries: Path.join(generated, 'zenodo', 'queries'),
98
+ zenodoResults: Path.join(generated, 'zenodo', 'results'),
99
+ lineage: Path.join(generated, 'lineage'),
100
+ datasets: Path.join(generated, 'datasets'),
101
+ queries: Path.join(generated, 'queries'),
102
+ results: Path.join(generated, 'results'),
103
+ manifest: Path.join(generated, 'manifest.json'),
104
+ };
105
+ }
106
+ /**
107
+ * The path of a dataset that the sources serve: an N-Triples file for a sample, or an HDT file for the full data.
108
+ * @param paths The paths of the generated files.
109
+ * @param dataset A dataset name.
110
+ */
111
+ getDatasetPath(paths, dataset) {
112
+ return Path.join(paths.datasets, `${dataset}.${this.sample ? 'nt' : 'hdt'}`);
113
+ }
114
+ async prepare(context, forceOverwriteGenerated) {
115
+ const paths = ExperimentLargeRdfBench.getPaths(context.experimentPaths.generated);
116
+ // Prepare hooks
117
+ await this.hookSparqlEndpoint.prepare(context, forceOverwriteGenerated);
118
+ for (const hook of this.hookSparqlEndpointSources) {
119
+ await hook.prepare(context, forceOverwriteGenerated);
120
+ }
121
+ // Ensure logs directory exists
122
+ await fs.ensureDir(Path.join(context.experimentPaths.output, 'logs'));
123
+ // The generated files may have been obtained elsewhere, such as a pre-built sample.
124
+ context.logger.info(`Preparing LargeRDFBench ${this.sample ? 'sample' : 'datasets'}, queries, and results`);
125
+ if (!forceOverwriteGenerated && await this.isGenerated(paths)) {
126
+ context.logger.info(` Skipped`);
127
+ return;
128
+ }
129
+ // Download the HDT files, queries, and published results
130
+ context.logger.info(`Downloading LargeRDFBench from Zenodo record ${this.zenodoRecord}`);
131
+ const log = (message) => {
132
+ context.logger.info(message);
133
+ };
134
+ const hdtFiles = new Set(this.datasets.flatMap(dataset => [`${dataset}.hdt`, `${dataset}.hdt.index.v1-1`]));
135
+ await new ZenodoArchive_1.ZenodoArchive(this.zenodoRecord, 'hdt_datasets.zip')
136
+ .extract(fileName => hdtFiles.has(fileName), this.sample ? paths.zenodoHdt : paths.datasets, log);
137
+ await new ZenodoArchive_1.ZenodoArchive(this.zenodoRecord, 'queries.zip')
138
+ .extract(fileName => fileName.endsWith('.sparql'), paths.zenodoQueries, log);
139
+ await new ZenodoArchive_1.ZenodoArchive(this.zenodoRecord, 'results.zip')
140
+ .extract(fileName => fileName.endsWith('.srj'), paths.zenodoResults, log);
141
+ // Write the queries, without blank lines, as sparql-benchmark-runner separates queries in a file by blank lines.
142
+ const queries = await this.readQueries(paths);
143
+ await fs.ensureDir(paths.queries);
144
+ for (const [id, query] of Object.entries(queries)) {
145
+ const lines = query.split('\n').filter(line => line.trim().length > 0);
146
+ await fs.writeFile(Path.join(paths.queries, `${id}.sparql`), `${lines.join('\n')}\n`, 'utf8');
147
+ }
148
+ const publishedResults = await this.readPublishedResults(paths);
149
+ if (this.sample) {
150
+ await this.generateSample(context, paths, queries, publishedResults);
151
+ }
152
+ else {
153
+ // The published results are used as expected results.
154
+ await this.writePublishedResults(paths, publishedResults);
155
+ await this.writeManifest(paths, {});
156
+ }
157
+ }
158
+ /**
159
+ * Check if all generated files that are needed to run the experiment exist.
160
+ * @param paths The paths of the generated files.
161
+ */
162
+ async isGenerated(paths) {
163
+ const files = [
164
+ paths.manifest,
165
+ ...this.datasets.map(dataset => this.getDatasetPath(paths, dataset)),
166
+ ...this.queries.map(id => Path.join(paths.queries, `${id}.sparql`)),
167
+ ];
168
+ for (const file of files) {
169
+ if (!await fs.pathExists(file)) {
170
+ return false;
171
+ }
172
+ }
173
+ return true;
174
+ }
175
+ /**
176
+ * Read the downloaded queries.
177
+ * @param paths The paths of the generated files.
178
+ */
179
+ async readQueries(paths) {
180
+ const queries = {};
181
+ for (const id of this.queries) {
182
+ queries[id] = await fs.readFile(Path.join(paths.zenodoQueries, `${id}.sparql`), 'utf8');
183
+ }
184
+ return queries;
185
+ }
186
+ /**
187
+ * Read the downloaded published results, preferring their corrected (complete) versions.
188
+ * @param paths The paths of the generated files.
189
+ */
190
+ async readPublishedResults(paths) {
191
+ const results = {};
192
+ for (const id of this.queries) {
193
+ for (const file of [`${id}_complete.srj`, `${id}.srj`]) {
194
+ const path = Path.join(paths.zenodoResults, file);
195
+ if (await fs.pathExists(path)) {
196
+ results[id] = JSON.parse(await fs.readFile(path, 'utf8'));
197
+ break;
198
+ }
199
+ }
200
+ }
201
+ return results;
202
+ }
203
+ /**
204
+ * Write the published results as expected results.
205
+ * @param paths The paths of the generated files.
206
+ * @param publishedResults The published results.
207
+ */
208
+ async writePublishedResults(paths, publishedResults) {
209
+ await fs.ensureDir(paths.results);
210
+ for (const [id, results] of Object.entries(publishedResults)) {
211
+ await fs.writeFile(Path.join(paths.results, `${id}.srj`), JSON.stringify(results), 'utf8');
212
+ }
213
+ }
214
+ /**
215
+ * Read the equivalent formulations of the queries that have one.
216
+ */
217
+ async readEquivalentQueries() {
218
+ const queries = {};
219
+ for (const id of this.queries) {
220
+ const file = ExperimentLargeRdfBench.EQUIVALENT_QUERIES[id];
221
+ if (file) {
222
+ queries[id] = await fs.readFile(Path.join(ExperimentLargeRdfBench.TEMPLATES_PATH, file), 'utf8');
223
+ }
224
+ }
225
+ return queries;
226
+ }
227
+ /**
228
+ * Generate the sampled datasets, the expected results, and the manifest.
229
+ * @param context The task context.
230
+ * @param paths The paths of the generated files.
231
+ * @param queries The queries.
232
+ * @param publishedResults The published results.
233
+ */
234
+ async generateSample(context, paths, queries, publishedResults) {
235
+ const log = (message) => {
236
+ context.logger.info(message);
237
+ };
238
+ // These are only loaded when generating a sample, as hdt is a native module.
239
+ const { hdt, QueryEngineHdt, QueryEngineRdfJs } = await ExperimentLargeRdfBench.loadGenerationModules();
240
+ const documents = {};
241
+ for (const dataset of this.datasets) {
242
+ documents[dataset] = await hdt.fromFile(Path.join(paths.zenodoHdt, `${dataset}.hdt`));
243
+ }
244
+ try {
245
+ const fullEngine = new QueryEngineHdt();
246
+ const fullContext = {
247
+ sources: this.datasets.map(dataset => ({ type: 'hdt', value: Path.join(paths.zenodoHdt, `${dataset}.hdt`) })),
248
+ };
249
+ const evaluationQueries = await this.readEquivalentQueries();
250
+ context.logger.info(`Computing the answer lineage of the queries`);
251
+ const lineage = await new LineageComputer_1.LineageComputer({
252
+ engine: fullEngine,
253
+ engineContext: fullContext,
254
+ documents,
255
+ queries,
256
+ evaluationQueries,
257
+ publishedResults,
258
+ limitCandidates: ExperimentLargeRdfBench.LIMIT_CANDIDATES,
259
+ timeoutSeconds: this.generationQueryTimeout,
260
+ lineageDirectory: paths.lineage,
261
+ resultsDirectory: paths.results,
262
+ log,
263
+ }).computeAll();
264
+ context.logger.info(`Sampling the datasets`);
265
+ const { datasets, patterns } = await new DatasetSampler_1.DatasetSampler({
266
+ documents,
267
+ queries: Object.values(queries),
268
+ subjectRates: this.sampleSubjectRates,
269
+ otherTriplesRate: this.sampleOtherTriplesRate,
270
+ seed: this.sampleSeed,
271
+ lineageDirectory: paths.lineage,
272
+ outputDirectory: paths.datasets,
273
+ log,
274
+ }).sampleAll();
275
+ let validation;
276
+ if (this.sampleValidate) {
277
+ context.logger.info(`Validating the sample`);
278
+ validation = await new SampleValidator_1.SampleValidator({
279
+ sampleEngine: new QueryEngineRdfJs(),
280
+ sampleContext: { sources: await this.loadSampleStores(paths) },
281
+ fullEngine,
282
+ fullContext,
283
+ queries,
284
+ evaluationQueries,
285
+ publishedResults,
286
+ resultsDirectory: paths.results,
287
+ sampleTimeoutSeconds: this.generationQueryTimeout,
288
+ fullTimeoutSeconds: this.generationQueryTimeout,
289
+ log,
290
+ }).validateAll();
291
+ const failed = Object.keys(validation).filter(id => !validation[id].ok);
292
+ if (failed.length > 0) {
293
+ throw new Error(`The sample does not produce the same results as the full data for ${failed.join(', ')}`);
294
+ }
295
+ }
296
+ else {
297
+ // The published results are used as expected results, next to the ones computed for the LIMIT queries.
298
+ await this.writePublishedResults(paths, publishedResults);
299
+ }
300
+ await this.writeManifest(paths, Object.assign({ seed: this.sampleSeed, subjectRates: this.sampleSubjectRates, otherTriplesRate: this.sampleOtherTriplesRate, datasets, sampleTriples: Object.values(datasets).reduce((sum, stats) => sum + stats.sampleTriples, 0), patterns, lineage: Object.fromEntries(Object.entries(lineage)
301
+ .map(([id, stats]) => [id, Object.assign(Object.assign({}, stats), { unmatchedRows: stats.unmatchedRows.length })])) }, validation ? { validation } : {}));
302
+ }
303
+ finally {
304
+ for (const document of Object.values(documents)) {
305
+ await document.close();
306
+ }
307
+ }
308
+ }
309
+ /**
310
+ * Load the modules that are needed to generate a sample.
311
+ */
312
+ static async loadGenerationModules() {
313
+ try {
314
+ return {
315
+ hdt: await Promise.resolve().then(() => __importStar(require('hdt'))),
316
+ QueryEngineHdt: (await Promise.resolve().then(() => __importStar(require('@comunica/query-sparql-hdt')))).QueryEngine,
317
+ QueryEngineRdfJs: (await Promise.resolve().then(() => __importStar(require('@comunica/query-sparql-rdfjs')))).QueryEngine,
318
+ };
319
+ }
320
+ catch (error) {
321
+ throw new Error(`Generating a LargeRDFBench sample requires the optional peer dependencies hdt, @comunica/query-sparql-hdt, and @comunica/query-sparql-rdfjs, which could not be loaded: ${error.message}`);
322
+ }
323
+ }
324
+ /**
325
+ * Load each sampled dataset into its own store, so that, as in a federation, matches in multiple datasets are not
326
+ * merged.
327
+ * @param paths The paths of the generated files.
328
+ */
329
+ async loadSampleStores(paths) {
330
+ const stores = [];
331
+ for (const dataset of this.datasets) {
332
+ const store = rdf_stores_1.RdfStore.createDefault();
333
+ const parser = new n3_1.StreamParser({ format: 'N-Triples' });
334
+ fs.createReadStream(this.getDatasetPath(paths, dataset)).pipe(parser);
335
+ await new Promise((resolve, reject) => store.import(parser).on('end', resolve).on('error', reject));
336
+ stores.push(store);
337
+ }
338
+ return stores;
339
+ }
340
+ /**
341
+ * Write the manifest, which describes how the generated files were obtained.
342
+ * @param paths The paths of the generated files.
343
+ * @param details Details on the sample.
344
+ */
345
+ async writeManifest(paths, details) {
346
+ const manifest = Object.assign({ source: `https://zenodo.org/records/${this.zenodoRecord}`, sample: this.sample, queries: this.queries }, details);
347
+ await fs.writeFile(paths.manifest, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
348
+ }
349
+ async run(context) {
350
+ await fs.ensureDir(Path.join(context.experimentPaths.output, 'logs'));
351
+ const startTime = performance.now();
352
+ const closeProcesses = [];
353
+ const processHandlers = [];
354
+ // Start the sources one by one, so that they do not load their datasets at the same time.
355
+ for (const [i, hook] of this.hookSparqlEndpointSources.entries()) {
356
+ const processHandler = await hook.start(context);
357
+ processHandlers.push(processHandler);
358
+ closeProcesses.push((0, jbr_1.secureProcessHandler)(processHandler, context));
359
+ if (this.sourceUrlsExternal[i]) {
360
+ await this.httpAvailabilityLatch.sleepUntilAvailable(context, this.sourceUrlsExternal[i]);
361
+ }
362
+ }
363
+ // Start the federation engine
364
+ const endpointProcessHandler = await this.hookSparqlEndpoint.start(context);
365
+ processHandlers.push(endpointProcessHandler);
366
+ closeProcesses.push((0, jbr_1.secureProcessHandler)(endpointProcessHandler, context));
367
+ await this.httpAvailabilityLatch.sleepUntilAvailable(context, this.endpointUrlExternal);
368
+ await fs.writeFile(Path.join(context.experimentPaths.output, 'logs', 'load-time.csv'), `time\n${Math.round(performance.now() - startTime)}`, 'utf-8');
369
+ // Determine query sets
370
+ const paths = ExperimentLargeRdfBench.getPaths(context.experimentPaths.generated);
371
+ let querySets = await new sparql_benchmark_runner_1.QueryLoaderFile({ path: paths.queries, extensions: ['.sparql'] }).loadQueries();
372
+ if (context.filter) {
373
+ const filterRegex = new RegExp(context.filter, 'u');
374
+ querySets = Object.fromEntries(Object.entries(querySets)
375
+ .filter(entry => filterRegex.test(entry[0])));
376
+ }
377
+ // Initiate SPARQL benchmark runner
378
+ const processHandlerComposite = new jbr_1.ProcessHandlerComposite(processHandlers);
379
+ let stopStats;
380
+ const results = await new sparql_benchmark_runner_1.SparqlBenchmarkRunner({
381
+ endpoint: this.endpointUrl,
382
+ endpointUpCheck: this.endpointUrlExternal,
383
+ querySets,
384
+ replication: this.queryRunnerReplication,
385
+ warmup: this.queryRunnerWarmupRounds,
386
+ requestDelay: this.queryRunnerRequestDelay,
387
+ availabilityCheckTimeout: this.queryRunnerEndpointAvailabilityCheckTimeout,
388
+ logger: (message) => process.stderr.write(`${message}\n`),
389
+ additionalUrlParams: new URLSearchParams(this.queryRunnerUrlParams),
390
+ timeout: this.queryTimeoutFallback,
391
+ recoveryQuery: 'ASK { ?s ?p ?o }',
392
+ }).runWithRawResults({
393
+ async onStart() {
394
+ // Collect stats
395
+ stopStats = await processHandlerComposite.startCollectingStats();
396
+ // Breakpoint right before starting queries.
397
+ if (context.breakpointBarrier) {
398
+ await context.breakpointBarrier();
399
+ }
400
+ },
401
+ async onStop() {
402
+ stopStats();
403
+ },
404
+ });
405
+ // Write results
406
+ const resultsOutput = context.experimentPaths.output;
407
+ context.logger.info(`Writing results to ${resultsOutput}\n`);
408
+ await new sparql_benchmark_runner_1.ResultSerializerCsv().serialize(Path.join(resultsOutput, 'query-times.csv'), results.aggregateResults);
409
+ if (results.rawResults) {
410
+ const resultSerializerRaw = new sparql_benchmark_runner_1.ResultSerializerRaw();
411
+ await resultSerializerRaw.serialize(Path.join(resultsOutput, 'query-results-raw.json'), results.rawResults);
412
+ }
413
+ // Close processes safely, the federation engine first
414
+ for (const closeProcess of closeProcesses.reverse()) {
415
+ await closeProcess();
416
+ }
417
+ }
418
+ async clean(context, cleanTargets) {
419
+ await this.hookSparqlEndpoint.clean(context, cleanTargets);
420
+ for (const hook of this.hookSparqlEndpointSources) {
421
+ await hook.clean(context, cleanTargets);
422
+ }
423
+ }
424
+ }
425
+ exports.ExperimentLargeRdfBench = ExperimentLargeRdfBench;
426
+ ExperimentLargeRdfBench.TEMPLATES_PATH = Path.join(__dirname, 'templates');
427
+ /**
428
+ * The 9 datasets that originate from FedBench.
429
+ */
430
+ ExperimentLargeRdfBench.FEDBENCH_DATASETS = [
431
+ 'ChEBI',
432
+ 'DBPedia-Subset',
433
+ 'DrugBank',
434
+ 'GeoNames',
435
+ 'Jamendo',
436
+ 'KEGG',
437
+ 'LMDB',
438
+ 'NYT',
439
+ 'SWDFood',
440
+ ];
441
+ /**
442
+ * The 23 queries that only use the FedBench datasets.
443
+ */
444
+ ExperimentLargeRdfBench.FEDBENCH_QUERIES = [
445
+ 'S1',
446
+ 'S2',
447
+ 'S3',
448
+ 'S4',
449
+ 'S5',
450
+ 'S6',
451
+ 'S7',
452
+ 'S8',
453
+ 'S9',
454
+ 'S10',
455
+ 'S11',
456
+ 'S12',
457
+ 'S13',
458
+ 'S14',
459
+ 'C1',
460
+ 'C2',
461
+ 'C3',
462
+ 'C4',
463
+ 'C5',
464
+ 'C6',
465
+ 'C7',
466
+ 'C8',
467
+ 'C9',
468
+ ];
469
+ /**
470
+ * Queries whose original form is too slow to generate a sample,
471
+ * mapped to an equivalent formulation in the templates directory.
472
+ */
473
+ ExperimentLargeRdfBench.EQUIVALENT_QUERIES = {
474
+ C2: 'equivalent-queries/C2.sparql',
475
+ C5: 'equivalent-queries/C5.sparql',
476
+ };
477
+ /**
478
+ * LIMIT queries whose full result is too expensive to compute, with candidate values for one of their variables.
479
+ */
480
+ ExperimentLargeRdfBench.LIMIT_CANDIDATES = {
481
+ C4: { variable: 'NYTplace', predicate: 'http://www.geonames.org/ontology#population', batchSize: 2000 },
482
+ };
483
+ //# sourceMappingURL=ExperimentLargeRdfBench.js.map
@@ -0,0 +1,183 @@
1
+ /// <reference types="node" />
2
+ import type { EventEmitter } from 'node:events';
3
+ import type * as RDF from '@rdfjs/types';
4
+ import type { Ordering } from '@traqula/rules-sparql-1-1';
5
+ /**
6
+ * The parts of an HDT document that are used.
7
+ */
8
+ export interface IHdtDocumentLike {
9
+ countTriples: (subject?: RDF.Term, predicate?: RDF.Term, object?: RDF.Term) => Promise<{
10
+ totalCount: number;
11
+ }>;
12
+ searchTriples: (subject?: RDF.Term, predicate?: RDF.Term, object?: RDF.Term, options?: {
13
+ offset?: number;
14
+ limit?: number;
15
+ }) => Promise<{
16
+ triples: RDF.Quad[];
17
+ }>;
18
+ }
19
+ /**
20
+ * The parts of a Comunica bindings stream that are used.
21
+ */
22
+ export type IBindingsStreamLike = EventEmitter & {
23
+ destroy: (cause?: Error) => void;
24
+ };
25
+ /**
26
+ * The parts of a Comunica query engine that are used.
27
+ */
28
+ export interface IQueryEngineLike {
29
+ queryBindings: (query: string, context: any) => Promise<IBindingsStreamLike>;
30
+ }
31
+ /**
32
+ * A term in the SPARQL 1.1 Query Results JSON Format.
33
+ */
34
+ export interface ISparqlJsonTerm {
35
+ type: string;
36
+ value: string;
37
+ 'xml:lang'?: string;
38
+ datatype?: string;
39
+ }
40
+ /**
41
+ * Results in the SPARQL 1.1 Query Results JSON Format.
42
+ */
43
+ export interface ISparqlJsonResults {
44
+ head: {
45
+ vars: string[];
46
+ };
47
+ results: {
48
+ bindings: Record<string, ISparqlJsonTerm>[];
49
+ };
50
+ }
51
+ /**
52
+ * For a LIMIT query whose full result is too expensive to compute, the candidate values for one of its variables:
53
+ * the subjects of the given predicate, which are tried in batches of the given size.
54
+ */
55
+ export interface ILimitCandidates {
56
+ variable: string;
57
+ predicate: string;
58
+ batchSize: number;
59
+ }
60
+ /**
61
+ * Statistics on the lineage of a query.
62
+ */
63
+ export interface ILineageStats {
64
+ expectedRows: number;
65
+ unmatchedRows: Record<string, string>[];
66
+ stillUnmatchedRows: number;
67
+ solutions: number;
68
+ triples: Record<string, number>;
69
+ seconds: number;
70
+ }
71
+ /**
72
+ * Evaluate a query to an array of bindings, failing after the timeout.
73
+ * @param engine A query engine.
74
+ * @param query A query string.
75
+ * @param context A query context.
76
+ * @param timeoutSeconds A timeout in seconds.
77
+ */
78
+ export declare function evaluate(engine: IQueryEngineLike, query: string, context: any, timeoutSeconds: number): Promise<RDF.Bindings[]>;
79
+ /**
80
+ * Convert a term in the SPARQL 1.1 Query Results JSON Format to an RDF term.
81
+ * @param term A term in the SPARQL 1.1 Query Results JSON Format.
82
+ */
83
+ export declare function jsonTermToRdf(term: ISparqlJsonTerm): RDF.Term;
84
+ /**
85
+ * Convert an RDF term to a term in the SPARQL 1.1 Query Results JSON Format.
86
+ * @param term An RDF term.
87
+ */
88
+ export declare function rdfTermToJson(term: RDF.Term): ISparqlJsonTerm;
89
+ /**
90
+ * Compare two solutions on the conditions of an ORDER BY, which may only contain variables.
91
+ * @param a A solution.
92
+ * @param b A solution.
93
+ * @param order The ORDER BY conditions of a parsed query.
94
+ */
95
+ export declare function compareOrder(a: RDF.Bindings, b: RDF.Bindings, order: Ordering[]): number;
96
+ /**
97
+ * Computes the answer lineage of queries over the full datasets: every triple, per dataset, that contributes to a
98
+ * solution.
99
+ * Queries with published expected results get those results bound via VALUES, so that the values of unprojected
100
+ * variables are recovered as well.
101
+ * Queries without published results (the LIMIT queries) are evaluated first, and their result is stored as their
102
+ * expected result.
103
+ */
104
+ export declare class LineageComputer {
105
+ readonly options: {
106
+ engine: IQueryEngineLike;
107
+ engineContext: any;
108
+ documents: Record<string, IHdtDocumentLike>;
109
+ queries: Record<string, string>;
110
+ evaluationQueries: Record<string, string>;
111
+ publishedResults: Record<string, ISparqlJsonResults | undefined>;
112
+ limitCandidates: Record<string, ILimitCandidates>;
113
+ timeoutSeconds: number;
114
+ lineageDirectory: string;
115
+ resultsDirectory: string;
116
+ log: (message: string) => void;
117
+ };
118
+ constructor(options: {
119
+ engine: IQueryEngineLike;
120
+ engineContext: any;
121
+ documents: Record<string, IHdtDocumentLike>;
122
+ queries: Record<string, string>;
123
+ evaluationQueries: Record<string, string>;
124
+ publishedResults: Record<string, ISparqlJsonResults | undefined>;
125
+ limitCandidates: Record<string, ILimitCandidates>;
126
+ timeoutSeconds: number;
127
+ lineageDirectory: string;
128
+ resultsDirectory: string;
129
+ log: (message: string) => void;
130
+ });
131
+ /**
132
+ * Compute the lineage of all queries, writing it as N-Triples per query and dataset, and statistics.
133
+ */
134
+ computeAll(): Promise<Record<string, ILineageStats>>;
135
+ /**
136
+ * The query used to evaluate the given query, which may be an equivalent formulation of it.
137
+ * @param id A query id.
138
+ */
139
+ getEvaluationQuery(id: string): string;
140
+ /**
141
+ * Compute the lineage of a single query.
142
+ * @param id A query id.
143
+ */
144
+ compute(id: string): Promise<ILineageStats>;
145
+ /**
146
+ * Compute the expected results of a query without published results, which has a LIMIT,
147
+ * so that any subset of the solutions of the right size is a correct result.
148
+ * To remain deterministic, all solutions are computed, sorted on the ORDER BY and their values,
149
+ * and the first ones are taken. The result is written to the results directory.
150
+ * @param id A query id.
151
+ */
152
+ computeExpectedResults(id: string): Promise<ISparqlJsonResults>;
153
+ /**
154
+ * Evaluate a LIMIT query on batches of candidate values for one variable, in a fixed order,
155
+ * until enough distinct projected rows are found.
156
+ * All these rows are actual solutions, and the outcome is deterministic.
157
+ * @param id A query id.
158
+ * @param text The query to evaluate.
159
+ * @param candidates The candidates configuration.
160
+ * @param needed The number of distinct rows that are needed.
161
+ */
162
+ evaluateOnCandidates(id: string, text: string, candidates: ILimitCandidates, needed: number): Promise<RDF.Bindings[]>;
163
+ /**
164
+ * Evaluate a query over the full data.
165
+ * @param query A query string.
166
+ */
167
+ evaluate(query: string): Promise<RDF.Bindings[]>;
168
+ /**
169
+ * The rows of results as maps from variable names to terms, without duplicates.
170
+ * @param results Results in the SPARQL 1.1 Query Results JSON Format.
171
+ */
172
+ static uniqueRows(results: ISparqlJsonResults): Record<string, RDF.Term>[];
173
+ /**
174
+ * The query with all variables projected and without solution modifiers, joined with the rows via VALUES.
175
+ * The full rows are joined last, so that their values never end up in solutions of an OPTIONAL that does not
176
+ * match them.
177
+ * The rows projected on the variables outside OPTIONAL and UNION are also joined first, which does not change the
178
+ * solutions, but lets the engine start from them.
179
+ * @param text A query string.
180
+ * @param rows Rows of variable bindings.
181
+ */
182
+ static lineageQuery(text: string, rows: Record<string, RDF.Term>[]): string;
183
+ }