@coasys/ad4m 0.13.0-test-2 → 0.13.0-test-3
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.
- package/lib/index.cjs +1060 -147
- package/lib/index.js +1054 -147
- package/lib/src/index.d.ts +0 -1
- package/lib/src/index.js +0 -1
- package/lib/src/language/Language.d.ts +26 -214
- package/lib/src/language/Language.js +28 -2
- package/lib/src/model/Ad4mModel.d.ts +25 -1
- package/lib/src/model/Ad4mModel.js +139 -30
- package/lib/src/model/Ad4mModel.test.js +214 -32
- package/lib/src/model/ModelQueryBuilder.d.ts +19 -0
- package/lib/src/model/ModelQueryBuilder.js +62 -18
- package/lib/src/model/hydration-batching.test.d.ts +7 -0
- package/lib/src/model/hydration-batching.test.js +456 -0
- package/lib/src/model/hydration.d.ts +1 -0
- package/lib/src/model/hydration.js +279 -70
- package/lib/src/model/query-sparql.d.ts +78 -1
- package/lib/src/model/query-sparql.js +447 -16
- package/lib/src/model/query-sparql.test.d.ts +1 -0
- package/lib/src/model/query-sparql.test.js +495 -0
- package/lib/src/model/query-utils.js +4 -0
- package/lib/src/model/subscription-delta.test.d.ts +24 -0
- package/lib/src/model/subscription-delta.test.js +180 -0
- package/lib/src/model/subscription-pool.js +48 -2
- package/lib/src/model/types.d.ts +49 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +2 -0
- package/lib/src/perspectives/PerspectiveClient.js +37 -9
- package/lib/src/perspectives/PerspectiveClient.test.d.ts +1 -0
- package/lib/src/perspectives/PerspectiveClient.test.js +169 -0
- package/lib/src/perspectives/PerspectiveProxy.d.ts +3 -0
- package/lib/src/perspectives/PerspectiveProxy.js +15 -0
- package/package.json +1 -1
- package/src/Ad4mClient.test.ts +56 -1
- package/src/index.ts +0 -1
- package/src/language/Language.ts +54 -275
- package/src/model/Ad4mModel.test.ts +222 -35
- package/src/model/Ad4mModel.ts +144 -30
- package/src/model/ModelQueryBuilder.ts +66 -18
- package/src/model/hydration-batching.test.ts +563 -0
- package/src/model/hydration.ts +249 -47
- package/src/model/query-sparql.test.ts +568 -0
- package/src/model/query-sparql.ts +473 -16
- package/src/model/query-utils.ts +4 -0
- package/src/model/subscription-delta.test.ts +207 -0
- package/src/model/subscription-pool.ts +50 -2
- package/src/model/types.ts +50 -1
- package/src/perspectives/PerspectiveClient.test.ts +204 -0
- package/src/perspectives/PerspectiveClient.ts +36 -7
- package/src/perspectives/PerspectiveProxy.ts +18 -0
- package/lib/src/model/query-surreal.d.ts +0 -44
- package/lib/src/model/query-surreal.js +0 -249
- package/lib/src/model/surreal-utils.d.ts +0 -42
- package/lib/src/model/surreal-utils.js +0 -128
- package/src/language/LanguageContext.ts +0 -37
- package/tsconfig-browser.json +0 -82
|
@@ -14,6 +14,65 @@ import { resolveParentPredicate } from "./query-common";
|
|
|
14
14
|
import type { RelationMetadataEntry } from "./decorators";
|
|
15
15
|
import type { Where, Query, ModelMetadata, PropertyMetadata } from "./types";
|
|
16
16
|
|
|
17
|
+
/**
|
|
18
|
+
* Check whether a `where` clause contains filters that cannot be pushed down
|
|
19
|
+
* to SPARQL and must be evaluated in JS after hydration.
|
|
20
|
+
*
|
|
21
|
+
* JS-only filters include:
|
|
22
|
+
* - Literal-stored properties (equality, comparison, contains, etc.)
|
|
23
|
+
* - Reverse relations (belongsToOne / belongsToMany)
|
|
24
|
+
* - author / timestamp filters (skipped by buildSPARQLWhereFilters)
|
|
25
|
+
*
|
|
26
|
+
* When JS-only filters exist, SPARQL-level LIMIT/OFFSET must NOT be applied
|
|
27
|
+
* because the database would cap the candidate set before JS filters run,
|
|
28
|
+
* potentially discarding matches beyond the LIMIT.
|
|
29
|
+
*/
|
|
30
|
+
export function hasJsOnlyWhereFilters(
|
|
31
|
+
metadata: ModelMetadata,
|
|
32
|
+
allRelationsMetadata: Record<string, RelationMetadataEntry>,
|
|
33
|
+
where?: Where,
|
|
34
|
+
): boolean {
|
|
35
|
+
if (!where) return false;
|
|
36
|
+
|
|
37
|
+
for (const [propertyName, condition] of Object.entries(where)) {
|
|
38
|
+
if (propertyName === "base" || propertyName === "id") continue;
|
|
39
|
+
|
|
40
|
+
// author/timestamp: return true so that count() falls back to the full hydration
|
|
41
|
+
// path (which uses buildSPARQLQuery — which DOES bind ?author/?timestamp via the
|
|
42
|
+
// named graph block). buildSPARQLCountQuery intentionally omits the named graph,
|
|
43
|
+
// so emitting an ?author FILTER there would produce unbound-variable SPARQL.
|
|
44
|
+
// buildSPARQLWhereFilters still pushes these into FILTER when called from
|
|
45
|
+
// buildSPARQLQuery / buildSPARQLGroupedCountQuery, which both include the named graph.
|
|
46
|
+
if (propertyName === "author" || propertyName === "timestamp") return true;
|
|
47
|
+
|
|
48
|
+
const propMeta = metadata.properties[propertyName];
|
|
49
|
+
if (!propMeta) continue;
|
|
50
|
+
|
|
51
|
+
// Reverse relations are JS-only
|
|
52
|
+
const relMeta = allRelationsMetadata[propertyName];
|
|
53
|
+
if (relMeta && (relMeta.kind === 'belongsToOne' || relMeta.kind === 'belongsToMany')) {
|
|
54
|
+
return true;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
// Literal-stored properties: equality/IN/NOT can be pushed to SPARQL via
|
|
58
|
+
// <ad4m://fn/parse_literal>(), but comparison operators (gt/lt/gte/lte/between/contains)
|
|
59
|
+
// must remain JS-only because parse_literal returns strings.
|
|
60
|
+
if (isLiteralStoredProperty(propMeta)) {
|
|
61
|
+
if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
|
|
62
|
+
const ops = condition as any;
|
|
63
|
+
const hasCompOps = ops.gt !== undefined || ops.gte !== undefined ||
|
|
64
|
+
ops.lt !== undefined || ops.lte !== undefined ||
|
|
65
|
+
ops.between !== undefined || ops.contains !== undefined;
|
|
66
|
+
if (hasCompOps) return true;
|
|
67
|
+
// NOT with simple value can be pushed to SPARQL — not JS-only
|
|
68
|
+
}
|
|
69
|
+
// Simple equality and IN filters can be pushed to SPARQL — not JS-only
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
return false;
|
|
74
|
+
}
|
|
75
|
+
|
|
17
76
|
/**
|
|
18
77
|
* Check if a string value looks like a URI (has a scheme).
|
|
19
78
|
*/
|
|
@@ -85,6 +144,31 @@ function iri(value: string): string {
|
|
|
85
144
|
return `<${value}>`;
|
|
86
145
|
}
|
|
87
146
|
|
|
147
|
+
/**
|
|
148
|
+
* Map a user-facing property name to the SPARQL variable alias used in the query.
|
|
149
|
+
*
|
|
150
|
+
* Properties appear in the query as:
|
|
151
|
+
* - Required properties: `?cfTarget_${name}`
|
|
152
|
+
* - Where-clause joins: `?wTarget_${name}`
|
|
153
|
+
* - Initial-value fallback: `?cfInitTarget_${name}`
|
|
154
|
+
*
|
|
155
|
+
* For ORDER BY, we prefer the conformance variable (always present for required props),
|
|
156
|
+
* then the where-target variable.
|
|
157
|
+
*/
|
|
158
|
+
function mapPropertyToSPARQLVar(propertyName: string, metadata: ModelMetadata): string {
|
|
159
|
+
const propMeta = metadata.properties[propertyName];
|
|
160
|
+
if (propMeta) {
|
|
161
|
+
if (propMeta.required && !propMeta.getter && !(propMeta.flag && propMeta.initial)) {
|
|
162
|
+
return `?cfTarget_${propertyName}`;
|
|
163
|
+
}
|
|
164
|
+
if (propMeta.initial && !propMeta.flag) {
|
|
165
|
+
return `?cfInitTarget_${propertyName}`;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
// Fallback: where-clause variable or raw name
|
|
169
|
+
return `?wTarget_${propertyName}`;
|
|
170
|
+
}
|
|
171
|
+
|
|
88
172
|
/**
|
|
89
173
|
* Build a SPARQL query that returns all links belonging to instances of
|
|
90
174
|
* the given model class, optionally filtered by `where` conditions.
|
|
@@ -177,6 +261,38 @@ export function buildSPARQLQuery(
|
|
|
177
261
|
? `FILTER(\n ${filterExpressions.join(" &&\n ")}\n )`
|
|
178
262
|
: "";
|
|
179
263
|
|
|
264
|
+
// Determine if SPARQL-level pagination is safe.
|
|
265
|
+
// When JS-only where filters exist, we must NOT limit at the SPARQL level
|
|
266
|
+
// because the database would cap candidates before JS filters run.
|
|
267
|
+
// Without an explicit ORDER BY, SPARQL OFFSET/LIMIT produces non-deterministic
|
|
268
|
+
// ordering across different query plans and index traversals. Fall back to
|
|
269
|
+
// JS-level slicing in that case to preserve the grouping order from the full
|
|
270
|
+
// result set.
|
|
271
|
+
const canPaginateInSPARQL = !hasJsOnlyWhereFilters(metadata, allRelationsMetadata, query.where)
|
|
272
|
+
&& (query.limit !== undefined || query.offset !== undefined)
|
|
273
|
+
&& query.order !== undefined && Object.keys(query.order).length > 0;
|
|
274
|
+
|
|
275
|
+
// Build a pagination subquery that constrains ?source to only the page
|
|
276
|
+
// of interest. This avoids fetching all links for all matching instances.
|
|
277
|
+
const paginationSubquery = canPaginateInSPARQL
|
|
278
|
+
? buildPaginationSubquery(joinPatterns, filterExpressions, metadata, query)
|
|
279
|
+
: '';
|
|
280
|
+
|
|
281
|
+
if (paginationSubquery) {
|
|
282
|
+
// Use the pagination subquery to constrain ?source, then fetch all links
|
|
283
|
+
// for those sources only.
|
|
284
|
+
return `
|
|
285
|
+
SELECT ?source ?predicate ?target ?author ?timestamp WHERE {
|
|
286
|
+
${paginationSubquery}${joinClause}
|
|
287
|
+
GRAPH ?linkGraph { ?source ?predicate ?target . }
|
|
288
|
+
FILTER(isIRI(?source) && isIRI(?predicate))
|
|
289
|
+
?linkGraph <ad4m://ontology/author> ?author .
|
|
290
|
+
?linkGraph <ad4m://ontology/timestamp> ?timestamp .
|
|
291
|
+
${filterClause}
|
|
292
|
+
}
|
|
293
|
+
`.trim();
|
|
294
|
+
}
|
|
295
|
+
|
|
180
296
|
return `
|
|
181
297
|
SELECT ?source ?predicate ?target ?author ?timestamp WHERE {${joinClause}
|
|
182
298
|
GRAPH ?linkGraph { ?source ?predicate ?target . }
|
|
@@ -191,11 +307,166 @@ export function buildSPARQLQuery(
|
|
|
191
307
|
|
|
192
308
|
/**
|
|
193
309
|
* Build ORDER BY / LIMIT / OFFSET clauses for the SPARQL query.
|
|
310
|
+
*
|
|
311
|
+
* NOTE: The outer SELECT returns multiple rows per instance (one per link),
|
|
312
|
+
* so LIMIT/OFFSET at the outer level would cut off links mid-instance.
|
|
313
|
+
* This function is kept for backward compatibility and always returns "".
|
|
314
|
+
* SPARQL-level pagination is handled via a subquery in buildSPARQLQuery
|
|
315
|
+
* using buildPaginationSubquery().
|
|
194
316
|
*/
|
|
195
|
-
function buildSPARQLOrderLimitOffset(_metadata: ModelMetadata,
|
|
317
|
+
export function buildSPARQLOrderLimitOffset(_metadata: ModelMetadata, query: Query): string {
|
|
196
318
|
return "";
|
|
197
319
|
}
|
|
198
320
|
|
|
321
|
+
/**
|
|
322
|
+
* Build an inner subquery that selects DISTINCT ?source URIs with
|
|
323
|
+
* ORDER BY, LIMIT, and OFFSET applied at the instance level.
|
|
324
|
+
*
|
|
325
|
+
* Because the outer SELECT returns multiple rows per instance (one per link),
|
|
326
|
+
* we cannot apply LIMIT/OFFSET there. Instead this subquery constrains
|
|
327
|
+
* ?source to only the instances on the requested page.
|
|
328
|
+
*
|
|
329
|
+
* @internal — used by buildSPARQLQuery when SPARQL-level pagination is safe.
|
|
330
|
+
*/
|
|
331
|
+
export function buildPaginationSubquery(
|
|
332
|
+
joinPatterns: string[],
|
|
333
|
+
filterExpressions: string[],
|
|
334
|
+
metadata: ModelMetadata,
|
|
335
|
+
query: Query,
|
|
336
|
+
): string {
|
|
337
|
+
const innerJoin = joinPatterns.join('\n');
|
|
338
|
+
const innerFilter = filterExpressions.length > 0
|
|
339
|
+
? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
|
|
340
|
+
: '';
|
|
341
|
+
|
|
342
|
+
// Build ORDER BY clause from query.order.
|
|
343
|
+
// When ORDER BY references non-grouped variables we must use SAMPLE()
|
|
344
|
+
// aggregates so the query is valid SPARQL 1.1.
|
|
345
|
+
let orderByClause = '';
|
|
346
|
+
const orderJoinPatterns: string[] = [];
|
|
347
|
+
const sampleProjections: string[] = []; // e.g. (SAMPLE(?cfTarget_title) AS ?pg_sort_0)
|
|
348
|
+
const needsGroupBy = query.order && Object.keys(query.order).length > 0;
|
|
349
|
+
|
|
350
|
+
if (query.order) {
|
|
351
|
+
let sortIdx = 0;
|
|
352
|
+
const orderTerms = Object.entries(query.order).map(([prop, dir]) => {
|
|
353
|
+
const sparqlVar = mapPropertyToSPARQLVar(prop, metadata);
|
|
354
|
+
// Check if this order property's variable is already bound by existing
|
|
355
|
+
// join patterns. If not, add an OPTIONAL join so ORDER BY is deterministic.
|
|
356
|
+
const varAlreadyBound = innerJoin.includes(sparqlVar);
|
|
357
|
+
if (!varAlreadyBound) {
|
|
358
|
+
const propMeta = metadata.properties[prop];
|
|
359
|
+
if (propMeta && propMeta.predicate && !propMeta.getter) {
|
|
360
|
+
orderJoinPatterns.push(`\n OPTIONAL { ?source <${propMeta.predicate}> ${sparqlVar} . }`);
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
// Use SAMPLE() aggregate so ORDER BY is valid with GROUP BY ?source.
|
|
364
|
+
const sortAlias = `?pg_sort_${sortIdx++}`;
|
|
365
|
+
sampleProjections.push(`(SAMPLE(${sparqlVar}) AS ${sortAlias})`);
|
|
366
|
+
return dir === 'DESC' ? `DESC(${sortAlias})` : `ASC(${sortAlias})`;
|
|
367
|
+
});
|
|
368
|
+
if (orderTerms.length > 0) {
|
|
369
|
+
orderByClause = `ORDER BY ${orderTerms.join(' ')}`;
|
|
370
|
+
}
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
const limitClause = query.limit !== undefined ? `LIMIT ${query.limit}` : '';
|
|
374
|
+
const offsetClause = query.offset !== undefined && query.offset > 0 ? `OFFSET ${query.offset}` : '';
|
|
375
|
+
|
|
376
|
+
// When there's no ORDER BY, DISTINCT alone handles deduplication — no GROUP BY needed.
|
|
377
|
+
// When there IS ORDER BY, use GROUP BY ?source with SAMPLE() aggregates for the sort keys.
|
|
378
|
+
const sampleSelect = sampleProjections.length > 0 ? ' ' + sampleProjections.join(' ') : '';
|
|
379
|
+
const groupByClause = needsGroupBy ? 'GROUP BY ?source' : '';
|
|
380
|
+
|
|
381
|
+
return `
|
|
382
|
+
{ SELECT DISTINCT ?source${sampleSelect} WHERE {${innerJoin}${orderJoinPatterns.join('')}
|
|
383
|
+
FILTER(isIRI(?source))
|
|
384
|
+
${innerFilter}
|
|
385
|
+
} ${groupByClause} ${orderByClause} ${limitClause} ${offsetClause} }\n`;
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
/**
|
|
389
|
+
* Build a SPARQL COUNT query that returns the total number of matching
|
|
390
|
+
* instances WITHOUT hydrating them. Uses the same WHERE clause as
|
|
391
|
+
* buildSPARQLQuery but wraps it in SELECT (COUNT(DISTINCT ?source) AS ?count).
|
|
392
|
+
*
|
|
393
|
+
* LIMIT/OFFSET from the query are stripped internally — this always counts
|
|
394
|
+
* the full result set.
|
|
395
|
+
*/
|
|
396
|
+
export function buildSPARQLCountQuery(
|
|
397
|
+
metadata: ModelMetadata,
|
|
398
|
+
allRelationsMetadata: Record<string, RelationMetadataEntry>,
|
|
399
|
+
query: Query,
|
|
400
|
+
modelClass: any,
|
|
401
|
+
): string {
|
|
402
|
+
// Build the same join/filter patterns as buildSPARQLQuery
|
|
403
|
+
const joinPatterns: string[] = [];
|
|
404
|
+
const filterExpressions: string[] = [];
|
|
405
|
+
|
|
406
|
+
if (query.parent) {
|
|
407
|
+
const parentPredicate = resolveParentPredicate(query.parent, modelClass);
|
|
408
|
+
joinPatterns.push(`\n ${iri(query.parent.id)} ${iri(parentPredicate)} ?source .`);
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
let hasConformance = false;
|
|
412
|
+
for (const [, propMeta] of Object.entries(metadata.properties)) {
|
|
413
|
+
if (propMeta.required) {
|
|
414
|
+
if (propMeta.getter) continue;
|
|
415
|
+
hasConformance = true;
|
|
416
|
+
if (propMeta.flag && propMeta.initial) {
|
|
417
|
+
joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
|
|
418
|
+
} else {
|
|
419
|
+
joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfTarget_${propMeta.name} .`);
|
|
420
|
+
}
|
|
421
|
+
}
|
|
422
|
+
}
|
|
423
|
+
|
|
424
|
+
if (!hasConformance) {
|
|
425
|
+
for (const [, propMeta] of Object.entries(metadata.properties)) {
|
|
426
|
+
if (propMeta.initial) {
|
|
427
|
+
hasConformance = true;
|
|
428
|
+
if (propMeta.flag) {
|
|
429
|
+
joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
|
|
430
|
+
} else {
|
|
431
|
+
joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfInitTarget_${propMeta.name} .`);
|
|
432
|
+
}
|
|
433
|
+
break;
|
|
434
|
+
}
|
|
435
|
+
}
|
|
436
|
+
}
|
|
437
|
+
|
|
438
|
+
if (!hasConformance && joinPatterns.length === 0) {
|
|
439
|
+
const knownPredicates: string[] = [];
|
|
440
|
+
for (const [, propMeta] of Object.entries(metadata.properties)) {
|
|
441
|
+
if (propMeta.predicate) knownPredicates.push(iri(propMeta.predicate));
|
|
442
|
+
}
|
|
443
|
+
if (metadata.relations) {
|
|
444
|
+
for (const [, relMeta] of Object.entries(metadata.relations)) {
|
|
445
|
+
if (relMeta.predicate) knownPredicates.push(iri(relMeta.predicate));
|
|
446
|
+
}
|
|
447
|
+
}
|
|
448
|
+
if (knownPredicates.length > 0) {
|
|
449
|
+
joinPatterns.push(`\n { SELECT DISTINCT ?source WHERE { ?source ?cf_structPred ?cf_structTarget . FILTER(?cf_structPred IN (${knownPredicates.join(", ")})) } }`);
|
|
450
|
+
}
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
const { joins: userJoins, filters: userFilters } = buildSPARQLWhereFilters(metadata, allRelationsMetadata, query.where);
|
|
454
|
+
joinPatterns.push(...userJoins);
|
|
455
|
+
filterExpressions.push(...userFilters);
|
|
456
|
+
|
|
457
|
+
const joinClause = joinPatterns.join('\n');
|
|
458
|
+
const filterClause = filterExpressions.length > 0
|
|
459
|
+
? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
|
|
460
|
+
: '';
|
|
461
|
+
|
|
462
|
+
return `
|
|
463
|
+
SELECT (COUNT(DISTINCT ?source) AS ?count) WHERE {${joinClause}
|
|
464
|
+
FILTER(isIRI(?source))
|
|
465
|
+
${filterClause}
|
|
466
|
+
}
|
|
467
|
+
`.trim();
|
|
468
|
+
}
|
|
469
|
+
|
|
199
470
|
/**
|
|
200
471
|
* Build a SPARQL query to fetch all links for a single instance.
|
|
201
472
|
*/
|
|
@@ -275,7 +546,46 @@ function buildSPARQLWhereFilters(
|
|
|
275
546
|
continue;
|
|
276
547
|
}
|
|
277
548
|
|
|
278
|
-
if (propertyName === "author"
|
|
549
|
+
if (propertyName === "author") {
|
|
550
|
+
// ?author is bound by the named graph block in buildSPARQLQuery /
|
|
551
|
+
// buildSPARQLGroupedCountQuery — push equality/IN filters into SPARQL.
|
|
552
|
+
if (Array.isArray(condition)) {
|
|
553
|
+
const formatted = (condition as any[]).map(v => formatSPARQLValue(String(v))).join(', ');
|
|
554
|
+
filters.push(`STR(?author) IN (${formatted})`);
|
|
555
|
+
} else if (typeof condition === 'object' && condition !== null) {
|
|
556
|
+
const ops = condition as any;
|
|
557
|
+
if (ops.not !== undefined) {
|
|
558
|
+
if (Array.isArray(ops.not)) {
|
|
559
|
+
const formatted = (ops.not as any[]).map((v: any) => formatSPARQLValue(String(v))).join(', ');
|
|
560
|
+
filters.push(`!(STR(?author) IN (${formatted}))`);
|
|
561
|
+
} else {
|
|
562
|
+
filters.push(`STR(?author) != ${formatSPARQLValue(String(ops.not))}`);
|
|
563
|
+
}
|
|
564
|
+
}
|
|
565
|
+
// Other operators (gt/lt/etc.) fall through to JS post-filter
|
|
566
|
+
} else {
|
|
567
|
+
filters.push(`STR(?author) = ${formatSPARQLValue(String(condition))}`);
|
|
568
|
+
}
|
|
569
|
+
continue;
|
|
570
|
+
}
|
|
571
|
+
|
|
572
|
+
if (propertyName === "timestamp") {
|
|
573
|
+
// ?timestamp is bound by the named graph block — push numeric comparisons.
|
|
574
|
+
if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
|
|
575
|
+
const ops = condition as any;
|
|
576
|
+
if (ops.gt !== undefined) filters.push(`?timestamp > ${Number(ops.gt)}`);
|
|
577
|
+
if (ops.gte !== undefined) filters.push(`?timestamp >= ${Number(ops.gte)}`);
|
|
578
|
+
if (ops.lt !== undefined) filters.push(`?timestamp < ${Number(ops.lt)}`);
|
|
579
|
+
if (ops.lte !== undefined) filters.push(`?timestamp <= ${Number(ops.lte)}`);
|
|
580
|
+
if (ops.between !== undefined && Array.isArray(ops.between)) {
|
|
581
|
+
filters.push(`?timestamp >= ${Number(ops.between[0])} && ?timestamp <= ${Number(ops.between[1])}`);
|
|
582
|
+
}
|
|
583
|
+
if (ops.not !== undefined) {
|
|
584
|
+
filters.push(`?timestamp != ${Number(ops.not)}`);
|
|
585
|
+
}
|
|
586
|
+
} else if (typeof condition === 'number' || (typeof condition === 'string' && !isNaN(Number(condition)))) {
|
|
587
|
+
filters.push(`?timestamp = ${Number(condition)}`);
|
|
588
|
+
}
|
|
279
589
|
continue;
|
|
280
590
|
}
|
|
281
591
|
|
|
@@ -293,32 +603,46 @@ function buildSPARQLWhereFilters(
|
|
|
293
603
|
// Determine if this property stores values as literal: IRIs
|
|
294
604
|
const useParseLiteral = isLiteralStoredProperty(propMeta);
|
|
295
605
|
|
|
296
|
-
// For literal-stored properties,
|
|
297
|
-
//
|
|
298
|
-
//
|
|
299
|
-
// (
|
|
300
|
-
//
|
|
606
|
+
// For literal-stored properties, push equality/IN/NOT filters to SPARQL using
|
|
607
|
+
// <ad4m://fn/parse_literal>() which extracts the raw value from literal: IRIs.
|
|
608
|
+
// The correct SPARQL syntax is <ad4m://fn/parse_literal>(?var) — NOT fn::parse_literal
|
|
609
|
+
// (which was SurrealDB syntax that Oxigraph rejects at parse time).
|
|
610
|
+
// Comparison operators (gt/lt/gte/lte/between/contains) remain JS-only because
|
|
611
|
+
// parse_literal returns strings and numeric/date comparisons would be unreliable.
|
|
612
|
+
// JS post-filter in instancesFromQueryResult remains as a safety net for all cases.
|
|
301
613
|
if (useParseLiteral) {
|
|
302
|
-
// Just ensure the property exists — no value filtering in SPARQL
|
|
303
614
|
if (typeof condition === "object" && condition !== null && !Array.isArray(condition)) {
|
|
304
615
|
const ops = condition as any;
|
|
305
616
|
const hasCompOps = ops.gt !== undefined || ops.gte !== undefined ||
|
|
306
617
|
ops.lt !== undefined || ops.lte !== undefined ||
|
|
307
|
-
ops.between !== undefined || ops.contains !== undefined
|
|
308
|
-
ops.not !== undefined;
|
|
618
|
+
ops.between !== undefined || ops.contains !== undefined;
|
|
309
619
|
if (hasCompOps) {
|
|
620
|
+
// Comparison operators: join only, filter in JS
|
|
310
621
|
joins.push(`
|
|
311
622
|
?source ${iri(propMeta.predicate)} ?wTarget_cmp_${propertyName} .`);
|
|
312
623
|
}
|
|
313
|
-
|
|
624
|
+
if (ops.not !== undefined) {
|
|
625
|
+
// NOT filter: push down to SPARQL
|
|
626
|
+
joins.push(`
|
|
627
|
+
?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
|
|
628
|
+
if (Array.isArray(ops.not)) {
|
|
629
|
+
const formatted = (ops.not as any[]).map((v: any) => formatSPARQLValue(v)).join(", ");
|
|
630
|
+
filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) NOT IN (${formatted})`);
|
|
631
|
+
} else {
|
|
632
|
+
filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) != ${formatSPARQLValue(ops.not)}`);
|
|
633
|
+
}
|
|
634
|
+
}
|
|
635
|
+
} else if (Array.isArray(condition)) {
|
|
636
|
+
// IN filter: push down to SPARQL
|
|
637
|
+
joins.push(`
|
|
638
|
+
?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
|
|
639
|
+
const formatted = (condition as any[]).map((v: any) => formatSPARQLValue(v)).join(", ");
|
|
640
|
+
filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) IN (${formatted})`);
|
|
314
641
|
} else {
|
|
315
|
-
// Simple equality
|
|
316
|
-
// NOTE: push-down FILTER with fn::parse_literal was attempted but removed because
|
|
317
|
-
// Oxigraph's query parser rejects the fn:: custom function syntax at parse time
|
|
318
|
-
// (custom functions are only available at execution time). All literal property
|
|
319
|
-
// filtering is done in JS post-filter after hydration resolves values.
|
|
642
|
+
// Simple equality: push down to SPARQL
|
|
320
643
|
joins.push(`
|
|
321
644
|
?source ${iri(propMeta.predicate)} ?wTarget_${propertyName} .`);
|
|
645
|
+
filters.push(`STR(<ad4m://fn/parse_literal>(?wTarget_${propertyName})) = ${formatSPARQLValue(condition)}`);
|
|
322
646
|
}
|
|
323
647
|
} else if (Array.isArray(condition)) {
|
|
324
648
|
const formatted = (condition as any[]).map(v => iri(v)).join(", ");
|
|
@@ -361,3 +685,136 @@ function buildSPARQLWhereFilters(
|
|
|
361
685
|
|
|
362
686
|
return { joins, filters };
|
|
363
687
|
}
|
|
688
|
+
|
|
689
|
+
/**
|
|
690
|
+
* Parse a SPARQL COUNT result row into a number.
|
|
691
|
+
* Handles `row.count?.value` (RDF binding), `row.count` (direct number/string),
|
|
692
|
+
* NaN results, and empty/malformed results.
|
|
693
|
+
*
|
|
694
|
+
* @returns The parsed count, or `null` if the result cannot be interpreted.
|
|
695
|
+
*/
|
|
696
|
+
export function parseSparqlCount(result: any[]): number | null {
|
|
697
|
+
if (!Array.isArray(result) || result.length === 0) return null;
|
|
698
|
+
const row = result[0];
|
|
699
|
+
const val = row.count?.value ?? row.count;
|
|
700
|
+
if (val === undefined || val === null) return null;
|
|
701
|
+
const parsed = typeof val === 'number' ? val : parseInt(String(val), 10);
|
|
702
|
+
return isNaN(parsed) ? null : parsed;
|
|
703
|
+
}
|
|
704
|
+
|
|
705
|
+
/**
|
|
706
|
+
* Build a SPARQL query that counts child instances grouped by parent IRI.
|
|
707
|
+
*
|
|
708
|
+
* Used by the projection Path A (`count: true`) in `hydrateRelations` to get
|
|
709
|
+
* per-parent counts in a single round-trip with zero instance hydration.
|
|
710
|
+
*
|
|
711
|
+
* Includes the full named graph block so that `?author` and `?timestamp` are
|
|
712
|
+
* bound and available for SPARQL FILTER expressions (unlike the intentionally
|
|
713
|
+
* minimal `buildSPARQLCountQuery` which omits them for speed).
|
|
714
|
+
*
|
|
715
|
+
* @param metadata - Model metadata for the **child** (target) class
|
|
716
|
+
* @param allRelationsMetadata - Relations metadata for the child class
|
|
717
|
+
* @param relationPredicate - The predicate linking `?parent` → `?source` (child)
|
|
718
|
+
* @param parentIds - IRI strings of all parent instances to count for
|
|
719
|
+
* @param where - Optional filter applied to child instances
|
|
720
|
+
*/
|
|
721
|
+
export function buildSPARQLGroupedCountQuery(
|
|
722
|
+
metadata: ModelMetadata,
|
|
723
|
+
allRelationsMetadata: Record<string, RelationMetadataEntry>,
|
|
724
|
+
relationPredicate: string,
|
|
725
|
+
parentIds: string[],
|
|
726
|
+
where?: import('./types').Where,
|
|
727
|
+
): string {
|
|
728
|
+
const joinPatterns: string[] = [];
|
|
729
|
+
const filterExpressions: string[] = [];
|
|
730
|
+
|
|
731
|
+
// Parent → child join and IN filter
|
|
732
|
+
joinPatterns.push(`\n ?parent ${iri(relationPredicate)} ?source .`);
|
|
733
|
+
const parentIris = parentIds.map(id => iri(id)).join(', ');
|
|
734
|
+
filterExpressions.push(`?parent IN (${parentIris})`);
|
|
735
|
+
|
|
736
|
+
// Conformance patterns (mirrors buildSPARQLCountQuery logic)
|
|
737
|
+
let hasConformance = false;
|
|
738
|
+
for (const [, propMeta] of Object.entries(metadata.properties)) {
|
|
739
|
+
if (propMeta.required) {
|
|
740
|
+
if (propMeta.getter) continue;
|
|
741
|
+
hasConformance = true;
|
|
742
|
+
if (propMeta.flag && propMeta.initial) {
|
|
743
|
+
joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
|
|
744
|
+
} else {
|
|
745
|
+
joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfTarget_${propMeta.name} .`);
|
|
746
|
+
}
|
|
747
|
+
}
|
|
748
|
+
}
|
|
749
|
+
|
|
750
|
+
if (!hasConformance) {
|
|
751
|
+
for (const [, propMeta] of Object.entries(metadata.properties)) {
|
|
752
|
+
if (propMeta.initial) {
|
|
753
|
+
hasConformance = true;
|
|
754
|
+
if (propMeta.flag) {
|
|
755
|
+
joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
|
|
756
|
+
} else {
|
|
757
|
+
joinPatterns.push(`\n ?source ${iri(propMeta.predicate)} ?cfInitTarget_${propMeta.name} .`);
|
|
758
|
+
}
|
|
759
|
+
break;
|
|
760
|
+
}
|
|
761
|
+
}
|
|
762
|
+
}
|
|
763
|
+
|
|
764
|
+
if (!hasConformance && joinPatterns.length <= 1) {
|
|
765
|
+
// Only the parent join so far — add open-world structural matching
|
|
766
|
+
const knownPredicates: string[] = [];
|
|
767
|
+
for (const [, propMeta] of Object.entries(metadata.properties)) {
|
|
768
|
+
if (propMeta.predicate) knownPredicates.push(iri(propMeta.predicate));
|
|
769
|
+
}
|
|
770
|
+
if (metadata.relations) {
|
|
771
|
+
for (const [, relMeta] of Object.entries(metadata.relations)) {
|
|
772
|
+
if (relMeta.predicate) knownPredicates.push(iri(relMeta.predicate));
|
|
773
|
+
}
|
|
774
|
+
}
|
|
775
|
+
if (knownPredicates.length > 0) {
|
|
776
|
+
joinPatterns.push(`\n { SELECT DISTINCT ?source WHERE { ?source ?cf_structPred ?cf_structTarget . FILTER(?cf_structPred IN (${knownPredicates.join(', ')})) } }`);
|
|
777
|
+
}
|
|
778
|
+
}
|
|
779
|
+
|
|
780
|
+
// User where-clause filters (including author/timestamp after the SPARQL push)
|
|
781
|
+
const { joins: userJoins, filters: userFilters } = buildSPARQLWhereFilters(metadata, allRelationsMetadata, where);
|
|
782
|
+
joinPatterns.push(...userJoins);
|
|
783
|
+
filterExpressions.push(...userFilters);
|
|
784
|
+
|
|
785
|
+
const joinClause = joinPatterns.join('\n');
|
|
786
|
+
const filterClause = filterExpressions.length > 0
|
|
787
|
+
? `FILTER(\n ${filterExpressions.join(' &&\n ')}\n )`
|
|
788
|
+
: '';
|
|
789
|
+
|
|
790
|
+
return `
|
|
791
|
+
SELECT ?parent (COUNT(DISTINCT ?source) AS ?count) WHERE {${joinClause}
|
|
792
|
+
GRAPH ?linkGraph { ?source ?predicate ?target . }
|
|
793
|
+
FILTER(isIRI(?source) && isIRI(?predicate))
|
|
794
|
+
?linkGraph <ad4m://ontology/author> ?author .
|
|
795
|
+
?linkGraph <ad4m://ontology/timestamp> ?timestamp .
|
|
796
|
+
${filterClause}
|
|
797
|
+
}
|
|
798
|
+
GROUP BY ?parent
|
|
799
|
+
`.trim();
|
|
800
|
+
}
|
|
801
|
+
|
|
802
|
+
/**
|
|
803
|
+
* Parse the result of `buildSPARQLGroupedCountQuery` into a map from parent IRI
|
|
804
|
+
* to count. Missing parents (zero matches) are absent from the map — callers
|
|
805
|
+
* should use `map.get(id) ?? 0`.
|
|
806
|
+
*
|
|
807
|
+
* @returns Map from parentId string → count number
|
|
808
|
+
*/
|
|
809
|
+
export function parseSparqlGroupedCount(result: any[]): Map<string, number> {
|
|
810
|
+
const out = new Map<string, number>();
|
|
811
|
+
if (!Array.isArray(result)) return out;
|
|
812
|
+
for (const row of result) {
|
|
813
|
+
const parentVal = row.parent?.value ?? row.parent;
|
|
814
|
+
const countVal = row.count?.value ?? row.count;
|
|
815
|
+
if (!parentVal || countVal === undefined || countVal === null) continue;
|
|
816
|
+
const parsed = typeof countVal === 'number' ? countVal : parseInt(String(countVal), 10);
|
|
817
|
+
if (!isNaN(parsed)) out.set(String(parentVal), parsed);
|
|
818
|
+
}
|
|
819
|
+
return out;
|
|
820
|
+
}
|
package/src/model/query-utils.ts
CHANGED
|
@@ -84,10 +84,14 @@ export function buildWhereCondition(
|
|
|
84
84
|
if (ops.not !== undefined) {
|
|
85
85
|
if (Array.isArray(ops.not)) {
|
|
86
86
|
const formattedValues = ops.not.map((v: any) => formatValue(v)).join(', ');
|
|
87
|
+
// FILTER NOT EXISTS here is scoped to a specific predicate, not a global scan,
|
|
88
|
+
// so O(N²) behavior is bounded by the number of values for this property.
|
|
87
89
|
parts.push(
|
|
88
90
|
`FILTER NOT EXISTS { ?target <${escapedPredicate}> ?_nval . FILTER(?_nval IN (${formattedValues})) }`,
|
|
89
91
|
);
|
|
90
92
|
} else {
|
|
93
|
+
// FILTER NOT EXISTS here is scoped to a specific predicate, not a global scan,
|
|
94
|
+
// so O(N²) behavior is bounded by the number of values for this property.
|
|
91
95
|
parts.push(
|
|
92
96
|
`FILTER NOT EXISTS { ?target <${escapedPredicate}> ${formatValue(ops.not)} }`,
|
|
93
97
|
);
|