@coasys/ad4m 0.12.1-dev → 0.13.0-test-2
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 +1469 -781
- package/lib/index.js +1453 -779
- package/lib/src/Literal.js +6 -5
- package/lib/src/agent/AgentClient.d.ts +8 -1
- package/lib/src/agent/AgentClient.js +73 -2
- package/lib/src/expression/ExpressionRef.js +2 -2
- package/lib/src/language/Language.d.ts +41 -3
- package/lib/src/model/Ad4mModel.d.ts +28 -28
- package/lib/src/model/Ad4mModel.js +129 -101
- package/lib/src/model/Ad4mModel.test.js +1543 -535
- package/lib/src/model/ModelQueryBuilder.d.ts +48 -34
- package/lib/src/model/ModelQueryBuilder.js +163 -78
- package/lib/src/model/Subject.js +6 -6
- package/lib/src/model/decorators.d.ts +14 -8
- package/lib/src/model/decorators.js +41 -14
- package/lib/src/model/hydration-batch.d.ts +34 -0
- package/lib/src/model/hydration-batch.js +147 -0
- package/lib/src/model/hydration.d.ts +3 -3
- package/lib/src/model/hydration.js +106 -36
- package/lib/src/model/index.d.ts +4 -1
- package/lib/src/model/index.js +4 -1
- package/lib/src/model/json-schema.js +2 -2
- package/lib/src/model/query-cache.d.ts +30 -0
- package/lib/src/model/query-cache.js +66 -0
- package/lib/src/model/query-cache.test.d.ts +1 -0
- package/lib/src/model/query-cache.test.js +43 -0
- package/lib/src/model/query-common.d.ts +1 -1
- package/lib/src/model/query-common.js +1 -1
- package/lib/src/model/query-sparql-batch.d.ts +17 -0
- package/lib/src/model/query-sparql-batch.js +260 -0
- package/lib/src/model/query-sparql.d.ts +47 -0
- package/lib/src/model/query-sparql.js +336 -0
- package/lib/src/model/query-utils.d.ts +45 -0
- package/lib/src/model/query-utils.js +140 -0
- package/lib/src/model/relation-filtering.test.js +15 -15
- package/lib/src/model/sdna.js +1 -1
- package/lib/src/model/shacl-gen.js +42 -18
- package/lib/src/model/subscription-pool.d.ts +39 -0
- package/lib/src/model/subscription-pool.js +119 -0
- package/lib/src/model/types.d.ts +3 -3
- package/lib/src/model/types.js +1 -1
- package/lib/src/perspectives/PerspectiveClient.d.ts +1 -17
- package/lib/src/perspectives/PerspectiveClient.js +5 -57
- package/lib/src/perspectives/PerspectiveProxy.d.ts +51 -30
- package/lib/src/perspectives/PerspectiveProxy.js +224 -177
- package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
- package/lib/src/perspectives/PerspectiveResolver.js +0 -11
- package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
- package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
- package/lib/src/runtime/RuntimeClient.d.ts +2 -0
- package/lib/src/runtime/RuntimeClient.js +17 -0
- package/lib/src/runtime/RuntimeResolver.d.ts +14 -0
- package/lib/src/runtime/RuntimeResolver.js +84 -0
- package/lib/src/schema.gql +14 -1
- package/lib/src/shacl/SHACLFlow.d.ts +1 -1
- package/lib/src/shacl/SHACLFlow.js +9 -9
- package/lib/src/shacl/SHACLShape.d.ts +1 -1
- package/lib/src/shacl/SHACLShape.js +38 -38
- package/lib/src/typeDefs.js +14 -1
- package/lib/src/utils.d.ts +6 -6
- package/lib/src/utils.js +6 -6
- package/package.json +1 -1
- package/src/Literal.test.ts +10 -5
- package/src/Literal.ts +6 -5
- package/src/agent/AgentClient.ts +81 -1
- package/src/expression/ExpressionRef.ts +2 -2
- package/src/language/Language.ts +48 -3
- package/src/model/Ad4mModel.test.ts +1515 -565
- package/src/model/Ad4mModel.ts +142 -102
- package/src/model/ModelQueryBuilder.ts +185 -86
- package/src/model/Subject.ts +6 -6
- package/src/model/decorators.ts +51 -22
- package/src/model/hydration-batch.ts +205 -0
- package/src/model/hydration.ts +102 -39
- package/src/model/index.ts +4 -1
- package/src/model/json-schema.ts +2 -2
- package/src/model/query-cache.test.ts +54 -0
- package/src/model/query-cache.ts +79 -0
- package/src/model/query-common.ts +1 -1
- package/src/model/query-sparql-batch.ts +301 -0
- package/src/model/query-sparql.ts +363 -0
- package/src/model/{surreal-utils.ts → query-utils.ts} +40 -27
- package/src/model/relation-filtering.test.ts +15 -15
- package/src/model/sdna.ts +1 -1
- package/src/model/shacl-gen.ts +42 -17
- package/src/model/subscription-pool.ts +163 -0
- package/src/model/types.ts +3 -3
- package/src/perspectives/PerspectiveClient.ts +5 -61
- package/src/perspectives/PerspectiveProxy.ts +226 -181
- package/src/perspectives/PerspectiveResolver.ts +0 -8
- package/src/perspectives/WakerSubscriptionManager.ts +8 -9
- package/src/runtime/RuntimeClient.ts +19 -0
- package/src/runtime/RuntimeResolver.ts +58 -0
- package/src/shacl/SHACLFlow.ts +9 -9
- package/src/shacl/SHACLShape.ts +39 -39
- package/src/utils.ts +6 -6
- package/src/model/query-surreal.ts +0 -280
package/src/model/Ad4mModel.ts
CHANGED
|
@@ -5,12 +5,15 @@ import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
|
|
|
5
5
|
import { makeRandomId } from "./util";
|
|
6
6
|
import { getPropertiesMetadata, getRelationsMetadata } from "./decorators";
|
|
7
7
|
import type { PropertyOptions, PropertyMetadataEntry, RelationMetadataEntry } from "./decorators";
|
|
8
|
-
import {
|
|
8
|
+
import { formatQueryValue } from "./query-utils";
|
|
9
9
|
import { resolveParentPredicate } from "./query-common";
|
|
10
10
|
import { buildParentQuery, buildAuthorAndTimestampQuery, buildPropertiesQuery, buildWhereQuery, buildCountQuery, buildOrderQuery, buildOffsetQuery, buildLimitQuery } from "./query-prolog";
|
|
11
11
|
import { isArrayType, determinePredicate, determineNamespace, buildModelFromJSONSchema } from "./json-schema";
|
|
12
12
|
import type { JSONSchemaProperty, JSONSchema, JSONSchemaToModelOptions } from "./json-schema";
|
|
13
|
-
|
|
13
|
+
|
|
14
|
+
import { buildSPARQLQuery, buildSPARQLGetDataQuery, groupSPARQLResults } from "./query-sparql";
|
|
15
|
+
import { buildBatchSPARQLQuery } from "./query-sparql-batch";
|
|
16
|
+
import { hydrateBatchResult } from "./hydration-batch";
|
|
14
17
|
import { ModelQueryBuilder } from "./ModelQueryBuilder";
|
|
15
18
|
import {
|
|
16
19
|
normalizeValue, matchesCondition, hydrateFromLinks,
|
|
@@ -341,7 +344,7 @@ export class Ad4mModel {
|
|
|
341
344
|
* const recipe = new Recipe(perspective);
|
|
342
345
|
*
|
|
343
346
|
* // Create with specific base expression
|
|
344
|
-
* const recipe = new Recipe(perspective, "literal
|
|
347
|
+
* const recipe = new Recipe(perspective, "literal:...");
|
|
345
348
|
* ```
|
|
346
349
|
*/
|
|
347
350
|
constructor(perspective: PerspectiveProxy, baseExpression?: string) {
|
|
@@ -601,20 +604,14 @@ export class Ad4mModel {
|
|
|
601
604
|
|
|
602
605
|
private async getData(opts?: GetOptions) {
|
|
603
606
|
// Builds an object with the author, timestamp, all properties, & all relations on the Ad4mModel and saves it to the instance
|
|
604
|
-
// Use
|
|
607
|
+
// Use SPARQL for data queries
|
|
605
608
|
try {
|
|
606
609
|
const ctor = this.constructor as typeof Ad4mModel;
|
|
607
610
|
const metadata = ctor.getModelMetadata();
|
|
608
611
|
|
|
609
612
|
// Query for all links from this specific node (base expression)
|
|
610
|
-
const
|
|
611
|
-
const
|
|
612
|
-
SELECT id, predicate, out.uri AS target, author, timestamp
|
|
613
|
-
FROM link
|
|
614
|
-
WHERE in.uri = ${safeBaseExpression}
|
|
615
|
-
ORDER BY timestamp ASC
|
|
616
|
-
`;
|
|
617
|
-
const links = await this._perspective.querySurrealDB(linksQuery);
|
|
613
|
+
const linksQuery = buildSPARQLGetDataQuery(this._baseExpression);
|
|
614
|
+
const links = await this._perspective.querySparql(linksQuery);
|
|
618
615
|
|
|
619
616
|
if (links && links.length > 0) {
|
|
620
617
|
// Core hydration: properties (latest-wins), relations, timestamps/author
|
|
@@ -641,7 +638,7 @@ export class Ad4mModel {
|
|
|
641
638
|
}
|
|
642
639
|
}
|
|
643
640
|
|
|
644
|
-
// Evaluate
|
|
641
|
+
// Evaluate SPARQL getters
|
|
645
642
|
const getterOpts = opts?.properties || opts?.include
|
|
646
643
|
? { requestedProperties: opts?.properties, include: opts?.include }
|
|
647
644
|
: undefined;
|
|
@@ -652,7 +649,7 @@ export class Ad4mModel {
|
|
|
652
649
|
await hydrateRelations(ctor, [this], this._perspective, opts.include);
|
|
653
650
|
}
|
|
654
651
|
} catch (e) {
|
|
655
|
-
console.error(`
|
|
652
|
+
console.error(`SPARQL getData also failed for ${this._baseExpression}:`, e);
|
|
656
653
|
}
|
|
657
654
|
|
|
658
655
|
this.takeSnapshot();
|
|
@@ -690,13 +687,13 @@ export class Ad4mModel {
|
|
|
690
687
|
}
|
|
691
688
|
|
|
692
689
|
/**
|
|
693
|
-
* Generates a
|
|
690
|
+
* Generates a SPARQL query from a Query object.
|
|
694
691
|
*
|
|
695
692
|
* @description
|
|
696
|
-
* This method translates high-level query parameters into a
|
|
697
|
-
* that can be executed against the
|
|
698
|
-
* operate on SDNA-aware predicates,
|
|
699
|
-
* stored in
|
|
693
|
+
* This method translates high-level query parameters into a SPARQL query string
|
|
694
|
+
* that can be executed against the SPARQL backend. Unlike Prolog queries which
|
|
695
|
+
* operate on SDNA-aware predicates, SPARQL queries operate directly on raw links
|
|
696
|
+
* stored in SPARQL.
|
|
700
697
|
*
|
|
701
698
|
* The generated query uses a CTE (Common Table Expression) pattern:
|
|
702
699
|
* 1. First, identify candidate base expressions by filtering links based on where conditions
|
|
@@ -704,7 +701,7 @@ export class Ad4mModel {
|
|
|
704
701
|
* 3. Finally, apply ordering, pagination (LIMIT/START) at the SQL level
|
|
705
702
|
*
|
|
706
703
|
* Key architectural notes:
|
|
707
|
-
* -
|
|
704
|
+
* - SPARQL stores only raw links (source, predicate, target, author, timestamp)
|
|
708
705
|
* - No SDNA knowledge at the database level
|
|
709
706
|
* - Properties are resolved via subqueries that look for links with specific predicates
|
|
710
707
|
* - Relations are similar but return multiple values instead of one
|
|
@@ -712,11 +709,11 @@ export class Ad4mModel {
|
|
|
712
709
|
*
|
|
713
710
|
* @param perspective - The perspective to query (used for metadata extraction)
|
|
714
711
|
* @param query - Query parameters (where, order, limit, offset, properties, relations)
|
|
715
|
-
* @returns Complete
|
|
712
|
+
* @returns Complete SPARQL query string ready for execution
|
|
716
713
|
*
|
|
717
714
|
* @example
|
|
718
715
|
* ```typescript
|
|
719
|
-
* const query = Recipe.
|
|
716
|
+
* const query = Recipe.queryToSPARQL(perspective, {
|
|
720
717
|
* where: { name: "Pasta", rating: { gt: 4 } },
|
|
721
718
|
* order: { timestamp: "DESC" },
|
|
722
719
|
* limit: 10
|
|
@@ -725,10 +722,10 @@ export class Ad4mModel {
|
|
|
725
722
|
* // FROM link WHERE ... GROUP BY source ORDER BY timestamp DESC LIMIT 10
|
|
726
723
|
* ```
|
|
727
724
|
*/
|
|
728
|
-
public static async
|
|
725
|
+
public static async queryToSPARQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
|
|
729
726
|
const metadata = this.getModelMetadata();
|
|
730
727
|
const allRelMeta = getRelationsMetadata(this as any);
|
|
731
|
-
return
|
|
728
|
+
return buildSPARQLQuery(metadata, allRelMeta, query, this);
|
|
732
729
|
}
|
|
733
730
|
|
|
734
731
|
public static async instancesFromPrologResult<T extends Ad4mModel>(
|
|
@@ -783,16 +780,16 @@ export class Ad4mModel {
|
|
|
783
780
|
}
|
|
784
781
|
|
|
785
782
|
/**
|
|
786
|
-
* Converts
|
|
783
|
+
* Converts SPARQL query results to Ad4mModel instances.
|
|
787
784
|
*
|
|
788
785
|
* @param perspective - The perspective context
|
|
789
786
|
* @param query - The query parameters used
|
|
790
|
-
* @param result - Array of result objects from
|
|
787
|
+
* @param result - Array of result objects from SPARQL
|
|
791
788
|
* @returns Promise resolving to results with total count
|
|
792
789
|
*
|
|
793
790
|
* @internal
|
|
794
791
|
*/
|
|
795
|
-
public static async
|
|
792
|
+
public static async instancesFromQueryResult<T extends Ad4mModel>(
|
|
796
793
|
this: typeof Ad4mModel & (new (...args: any[]) => T),
|
|
797
794
|
perspective: PerspectiveProxy,
|
|
798
795
|
query: Query,
|
|
@@ -824,34 +821,26 @@ export class Ad4mModel {
|
|
|
824
821
|
|
|
825
822
|
const instance = new this(perspective, base) as any;
|
|
826
823
|
|
|
827
|
-
// Core hydration via unified helper (pass requestedProperties for sparse fieldset)
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
if (!requested.has(propName)) {
|
|
836
|
-
delete instance[propName];
|
|
837
|
-
}
|
|
838
|
-
}
|
|
839
|
-
for (const relName of Object.keys(metadata.relations)) {
|
|
840
|
-
if (!requested.has(relName) && !(query.include && relName in query.include)) {
|
|
841
|
-
delete instance[relName];
|
|
842
|
-
}
|
|
843
|
-
}
|
|
844
|
-
// Also strip metadata fields unless explicitly requested
|
|
845
|
-
for (const metaField of ['author', 'createdAt', 'updatedAt'] as const) {
|
|
846
|
-
if (!requested.has(metaField)) {
|
|
847
|
-
delete instance[metaField];
|
|
824
|
+
// Core hydration via unified helper (pass requestedProperties for sparse fieldset).
|
|
825
|
+
// Also hydrate any properties referenced in `where` so the JS post-filter can match them,
|
|
826
|
+
// even if they're not in the user's `properties` projection.
|
|
827
|
+
let hydrationProps = requestedProperties.length > 0 ? [...requestedProperties] : undefined;
|
|
828
|
+
if (hydrationProps && query.where) {
|
|
829
|
+
for (const key of Object.keys(query.where)) {
|
|
830
|
+
if (!hydrationProps.includes(key)) {
|
|
831
|
+
hydrationProps.push(key);
|
|
848
832
|
}
|
|
849
833
|
}
|
|
850
834
|
}
|
|
835
|
+
await hydrateFromLinks(instance, links, metadata, perspective, hydrationProps);
|
|
836
|
+
|
|
837
|
+
// NOTE: Property deletion for sparse fieldsets is deferred until AFTER
|
|
838
|
+
// where-filtering so that where conditions can reference any property,
|
|
839
|
+
// even ones not in the `properties` projection.
|
|
851
840
|
|
|
852
841
|
instances.push(instance);
|
|
853
842
|
} catch (error) {
|
|
854
|
-
console.error(`Failed to process
|
|
843
|
+
console.error(`Failed to process SPARQL instance ${base}:`, error);
|
|
855
844
|
}
|
|
856
845
|
}
|
|
857
846
|
|
|
@@ -893,17 +882,19 @@ export class Ad4mModel {
|
|
|
893
882
|
await evaluateCustomGettersForInstance(instance, perspective, metadata, getterOpts);
|
|
894
883
|
}
|
|
895
884
|
|
|
896
|
-
// Filter by where conditions that couldn't be filtered in
|
|
885
|
+
// Filter by where conditions that couldn't be filtered in SPARQL
|
|
897
886
|
// This includes:
|
|
898
887
|
// - author/timestamp (computed from grouped links)
|
|
899
888
|
// - Properties with comparison operators (gt, gte, lt, lte, between, contains)
|
|
900
|
-
// because fn::parse_literal() comparisons in
|
|
889
|
+
// because fn::parse_literal() comparisons in SPARQL subqueries don't work reliably
|
|
890
|
+
// - Relation-based where clauses (e.g., { post: postId } for @BelongsToOne)
|
|
891
|
+
// which require reverse-link resolution before filtering
|
|
901
892
|
let filteredInstances = instances;
|
|
902
893
|
if (query.where) {
|
|
903
894
|
filteredInstances = instances.filter(instance => {
|
|
904
895
|
for (const [propertyName, condition] of Object.entries(query.where!)) {
|
|
905
|
-
// Skip 'base' as it's filtered in
|
|
906
|
-
if (propertyName === 'base') continue;
|
|
896
|
+
// Skip 'base'/'id' as it's filtered in SPARQL
|
|
897
|
+
if (propertyName === 'base' || propertyName === 'id') continue;
|
|
907
898
|
|
|
908
899
|
// For author and timestamp, always filter in JS
|
|
909
900
|
if (propertyName === 'author' || propertyName === 'timestamp') {
|
|
@@ -913,19 +904,22 @@ export class Ad4mModel {
|
|
|
913
904
|
continue;
|
|
914
905
|
}
|
|
915
906
|
|
|
916
|
-
//
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
//
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
ops.between !== undefined || ops.contains !== undefined;
|
|
924
|
-
if (hasComparisonOps) {
|
|
925
|
-
if (!matchesCondition(instance[propertyName], condition)) {
|
|
926
|
-
return false;
|
|
927
|
-
}
|
|
907
|
+
// Check if this is a relation field (not in properties metadata)
|
|
908
|
+
const isPropField = propertyName in metadata.properties;
|
|
909
|
+
|
|
910
|
+
if (!isPropField) {
|
|
911
|
+
// Relation-based where — filter in JS against the populated field
|
|
912
|
+
if (!matchesCondition(instance[propertyName], condition)) {
|
|
913
|
+
return false;
|
|
928
914
|
}
|
|
915
|
+
continue;
|
|
916
|
+
}
|
|
917
|
+
|
|
918
|
+
// Filter ALL property conditions in JS (equality, NOT, IN, comparison operators).
|
|
919
|
+
// SPARQL-level filtering with parse_literal is unreliable across environments,
|
|
920
|
+
// so we do all property filtering here after hydration resolves values.
|
|
921
|
+
if (!matchesCondition(instance[propertyName], condition)) {
|
|
922
|
+
return false;
|
|
929
923
|
}
|
|
930
924
|
}
|
|
931
925
|
return true;
|
|
@@ -981,6 +975,29 @@ export class Ad4mModel {
|
|
|
981
975
|
paginatedInstances = filteredInstances.slice(start, end);
|
|
982
976
|
}
|
|
983
977
|
|
|
978
|
+
// Now that where-filtering is done, strip unrequested properties for sparse fieldsets.
|
|
979
|
+
// This must happen AFTER where-filtering so conditions can reference any property.
|
|
980
|
+
if (requestedProperties.length > 0) {
|
|
981
|
+
const requested = new Set(requestedProperties);
|
|
982
|
+
for (const inst of paginatedInstances) {
|
|
983
|
+
for (const propName of Object.keys(metadata.properties)) {
|
|
984
|
+
if (!requested.has(propName)) {
|
|
985
|
+
delete (inst as any)[propName];
|
|
986
|
+
}
|
|
987
|
+
}
|
|
988
|
+
for (const relName of Object.keys(metadata.relations)) {
|
|
989
|
+
if (!requested.has(relName) && !(query.include && relName in query.include)) {
|
|
990
|
+
delete (inst as any)[relName];
|
|
991
|
+
}
|
|
992
|
+
}
|
|
993
|
+
for (const metaField of ['author', 'createdAt', 'updatedAt'] as const) {
|
|
994
|
+
if (!requested.has(metaField)) {
|
|
995
|
+
delete (inst as any)[metaField];
|
|
996
|
+
}
|
|
997
|
+
}
|
|
998
|
+
}
|
|
999
|
+
}
|
|
1000
|
+
|
|
984
1001
|
// Eager-load relations if requested (BEFORE snapshot so dirty tracking is accurate)
|
|
985
1002
|
if (query.include && paginatedInstances.length > 0) {
|
|
986
1003
|
await hydrateRelations(this, paginatedInstances, perspective, query.include);
|
|
@@ -1008,15 +1025,15 @@ export class Ad4mModel {
|
|
|
1008
1025
|
*
|
|
1009
1026
|
* @param perspective - The perspective to search in
|
|
1010
1027
|
* @param query - Optional query parameters to filter results
|
|
1011
|
-
* @param
|
|
1028
|
+
* @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
|
|
1012
1029
|
* @returns Array of matching models
|
|
1013
1030
|
*
|
|
1014
1031
|
* @example
|
|
1015
1032
|
* ```typescript
|
|
1016
|
-
* // Get all recipes (uses
|
|
1033
|
+
* // Get all recipes (uses SPARQL by default)
|
|
1017
1034
|
* const allRecipes = await Recipe.findAll(perspective);
|
|
1018
1035
|
*
|
|
1019
|
-
* // Get recipes with specific criteria (uses
|
|
1036
|
+
* // Get recipes with specific criteria (uses SPARQL)
|
|
1020
1037
|
* const recipes = await Recipe.findAll(perspective, {
|
|
1021
1038
|
* where: {
|
|
1022
1039
|
* name: "Pasta",
|
|
@@ -1034,15 +1051,26 @@ export class Ad4mModel {
|
|
|
1034
1051
|
this: typeof Ad4mModel & (new (...args: any[]) => T),
|
|
1035
1052
|
perspective: PerspectiveProxy,
|
|
1036
1053
|
query: Query = {},
|
|
1037
|
-
|
|
1054
|
+
engine: 'sparql' | 'prolog' | boolean = 'sparql'
|
|
1038
1055
|
): Promise<T[]> {
|
|
1039
1056
|
if (query.properties && query.properties.length === 0) {
|
|
1040
1057
|
throw new Error("properties[] must not be empty — omit the field to return all properties, or specify at least one field name");
|
|
1041
1058
|
}
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1059
|
+
|
|
1060
|
+
// Backward compatibility: boolean maps to sparql (true) or prolog (false)
|
|
1061
|
+
const resolvedEngine = typeof engine === 'boolean'
|
|
1062
|
+
? (engine ? 'sparql' : 'prolog')
|
|
1063
|
+
: engine;
|
|
1064
|
+
|
|
1065
|
+
if (resolvedEngine === 'sparql') {
|
|
1066
|
+
// Always use the regular SPARQL path + JS-level hydrateRelations for includes.
|
|
1067
|
+
// The batch SPARQL approach had issues with sub-queries (where/order/limit on includes),
|
|
1068
|
+
// non-conforming node filtering, and parse_literal compatibility.
|
|
1069
|
+
// hydrateRelations handles all of these correctly via per-relation findAll calls.
|
|
1070
|
+
const sparqlQuery = await this.queryToSPARQL(perspective, query);
|
|
1071
|
+
const rawResult = await perspective.querySparql(sparqlQuery);
|
|
1072
|
+
const grouped = groupSPARQLResults(rawResult);
|
|
1073
|
+
const { results } = await this.instancesFromQueryResult(perspective, query, grouped);
|
|
1046
1074
|
return results;
|
|
1047
1075
|
} else {
|
|
1048
1076
|
const prologQuery = await this.queryToProlog(perspective, query);
|
|
@@ -1059,7 +1087,7 @@ export class Ad4mModel {
|
|
|
1059
1087
|
*
|
|
1060
1088
|
* @param perspective - The perspective to search in
|
|
1061
1089
|
* @param query - Optional query parameters to filter results
|
|
1062
|
-
* @param
|
|
1090
|
+
* @param useSPARQL - Whether to use SPARQL (default: true) or Prolog (legacy)
|
|
1063
1091
|
* @returns The first matching instance, or `null`
|
|
1064
1092
|
*
|
|
1065
1093
|
* @example
|
|
@@ -1076,10 +1104,10 @@ export class Ad4mModel {
|
|
|
1076
1104
|
this: typeof Ad4mModel & (new (...args: any[]) => T),
|
|
1077
1105
|
perspective: PerspectiveProxy,
|
|
1078
1106
|
query: Query = {},
|
|
1079
|
-
|
|
1107
|
+
engine: 'sparql' | 'prolog' | boolean = 'sparql',
|
|
1080
1108
|
): Promise<T | null> {
|
|
1081
1109
|
const limitedQuery = { ...query, limit: 1 };
|
|
1082
|
-
const results = await this.findAll(perspective, limitedQuery,
|
|
1110
|
+
const results = await this.findAll(perspective, limitedQuery, engine);
|
|
1083
1111
|
return results[0] ?? null;
|
|
1084
1112
|
}
|
|
1085
1113
|
|
|
@@ -1088,7 +1116,7 @@ export class Ad4mModel {
|
|
|
1088
1116
|
*
|
|
1089
1117
|
* @param perspective - The perspective to search in
|
|
1090
1118
|
* @param query - Optional query parameters to filter results
|
|
1091
|
-
* @param
|
|
1119
|
+
* @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
|
|
1092
1120
|
* @returns Object containing results array and total count
|
|
1093
1121
|
*
|
|
1094
1122
|
* @example
|
|
@@ -1107,12 +1135,17 @@ export class Ad4mModel {
|
|
|
1107
1135
|
this: typeof Ad4mModel & (new (...args: any[]) => T),
|
|
1108
1136
|
perspective: PerspectiveProxy,
|
|
1109
1137
|
query: Query = {},
|
|
1110
|
-
|
|
1138
|
+
engine: 'sparql' | 'prolog' | boolean = 'sparql'
|
|
1111
1139
|
): Promise<ResultsWithTotalCount<T>> {
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
-
|
|
1115
|
-
|
|
1140
|
+
const resolvedEngine = typeof engine === 'boolean'
|
|
1141
|
+
? (engine ? 'sparql' : 'prolog')
|
|
1142
|
+
: engine;
|
|
1143
|
+
|
|
1144
|
+
if (resolvedEngine === 'sparql') {
|
|
1145
|
+
const sparqlQuery = await this.queryToSPARQL(perspective, query);
|
|
1146
|
+
const rawResult = await perspective.querySparql(sparqlQuery);
|
|
1147
|
+
const grouped = groupSPARQLResults(rawResult);
|
|
1148
|
+
return await this.instancesFromQueryResult(perspective, query, grouped);
|
|
1116
1149
|
} else {
|
|
1117
1150
|
const prologQuery = await this.queryToProlog(perspective, query);
|
|
1118
1151
|
const result = await perspective.infer(prologQuery);
|
|
@@ -1127,7 +1160,7 @@ export class Ad4mModel {
|
|
|
1127
1160
|
* @param pageSize - Number of items per page
|
|
1128
1161
|
* @param pageNumber - Which page to retrieve (1-based)
|
|
1129
1162
|
* @param query - Optional additional query parameters
|
|
1130
|
-
* @param
|
|
1163
|
+
* @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
|
|
1131
1164
|
* @returns Paginated results with metadata
|
|
1132
1165
|
*
|
|
1133
1166
|
* @example
|
|
@@ -1147,13 +1180,18 @@ export class Ad4mModel {
|
|
|
1147
1180
|
pageSize: number,
|
|
1148
1181
|
pageNumber: number,
|
|
1149
1182
|
query?: Query,
|
|
1150
|
-
|
|
1183
|
+
engine: 'sparql' | 'prolog' | boolean = 'sparql'
|
|
1151
1184
|
): Promise<PaginationResult<T>> {
|
|
1152
1185
|
const paginationQuery = { ...(query || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1186
|
+
const resolvedEngine = typeof engine === 'boolean'
|
|
1187
|
+
? (engine ? 'sparql' : 'prolog')
|
|
1188
|
+
: engine;
|
|
1189
|
+
|
|
1190
|
+
if (resolvedEngine === 'sparql') {
|
|
1191
|
+
const sparqlQuery = await this.queryToSPARQL(perspective, paginationQuery);
|
|
1192
|
+
const rawResult = await perspective.querySparql(sparqlQuery);
|
|
1193
|
+
const grouped = groupSPARQLResults(rawResult);
|
|
1194
|
+
const { results, totalCount } = await this.instancesFromQueryResult(perspective, paginationQuery, grouped);
|
|
1157
1195
|
return { results, totalCount, pageSize, pageNumber };
|
|
1158
1196
|
} else {
|
|
1159
1197
|
const prologQuery = await this.queryToProlog(perspective, paginationQuery);
|
|
@@ -1185,21 +1223,21 @@ export class Ad4mModel {
|
|
|
1185
1223
|
}
|
|
1186
1224
|
|
|
1187
1225
|
/**
|
|
1188
|
-
* Generates a
|
|
1226
|
+
* Generates a SPARQL COUNT query for the model.
|
|
1189
1227
|
*
|
|
1190
1228
|
* @param perspective - The perspective context
|
|
1191
1229
|
* @param query - Query parameters to filter the count
|
|
1192
|
-
* @returns
|
|
1230
|
+
* @returns SPARQL COUNT query string
|
|
1193
1231
|
*
|
|
1194
1232
|
* @private
|
|
1195
1233
|
*/
|
|
1196
|
-
public static async
|
|
1234
|
+
public static async countQueryToSPARQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
|
|
1197
1235
|
// Use the same query as the main query (with GROUP BY), just without LIMIT/OFFSET
|
|
1198
1236
|
// We'll count the number of rows returned (one row per source)
|
|
1199
1237
|
const countQuery = { ...query };
|
|
1200
1238
|
delete countQuery.limit;
|
|
1201
1239
|
delete countQuery.offset;
|
|
1202
|
-
return await this.
|
|
1240
|
+
return await this.queryToSPARQL(perspective, countQuery);
|
|
1203
1241
|
}
|
|
1204
1242
|
|
|
1205
1243
|
/**
|
|
@@ -1207,7 +1245,7 @@ export class Ad4mModel {
|
|
|
1207
1245
|
*
|
|
1208
1246
|
* @param perspective - The perspective to search in
|
|
1209
1247
|
* @param query - Optional query parameters to filter results
|
|
1210
|
-
* @param
|
|
1248
|
+
* @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
|
|
1211
1249
|
* @returns Total count of matching entities
|
|
1212
1250
|
*
|
|
1213
1251
|
* @example
|
|
@@ -1221,14 +1259,16 @@ export class Ad4mModel {
|
|
|
1221
1259
|
* const countProlog = await Recipe.count(perspective, {}, false);
|
|
1222
1260
|
* ```
|
|
1223
1261
|
*/
|
|
1224
|
-
static async count(perspective: PerspectiveProxy, query: Query = {},
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
const
|
|
1262
|
+
static async count(perspective: PerspectiveProxy, query: Query = {}, engine: 'sparql' | 'prolog' | boolean = 'sparql') {
|
|
1263
|
+
const resolvedEngine = typeof engine === 'boolean'
|
|
1264
|
+
? (engine ? 'sparql' : 'prolog')
|
|
1265
|
+
: engine;
|
|
1266
|
+
|
|
1267
|
+
if (resolvedEngine === 'sparql') {
|
|
1268
|
+
const sparqlQuery = await this.queryToSPARQL(perspective, query);
|
|
1269
|
+
const rawResult = await perspective.querySparql(sparqlQuery);
|
|
1270
|
+
const grouped = groupSPARQLResults(rawResult);
|
|
1271
|
+
const { totalCount } = await this.instancesFromQueryResult(perspective, query, grouped);
|
|
1232
1272
|
return totalCount;
|
|
1233
1273
|
} else {
|
|
1234
1274
|
const result = await perspective.infer(await this.countQueryToProlog(perspective, query));
|
|
@@ -1249,7 +1289,7 @@ export class Ad4mModel {
|
|
|
1249
1289
|
// Get resolve language from metadata (replaces Prolog query)
|
|
1250
1290
|
let resolveLanguage = metadata.resolveLanguage;
|
|
1251
1291
|
|
|
1252
|
-
// Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal
|
|
1292
|
+
// Skip storing empty/null/undefined values to avoid invalid empty literals (e.g. literal:string:)
|
|
1253
1293
|
if (value === undefined || value === null || value === "") {
|
|
1254
1294
|
return;
|
|
1255
1295
|
}
|