holos-wasm-node 0.18.0 → 0.20.0

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/README.md CHANGED
@@ -46,10 +46,41 @@ store.dump('nquads'); // everything the store holds
46
46
  | What you get back | From |
47
47
  |---|---|
48
48
  | `true` / `false` | ASK |
49
- | terms in rdf-js shape — `{termType, value}`, plus `language` and `datatype` on a literal | SELECT |
49
+ | terms in rdf-js shape — `{termType, value}`, plus `language`, `direction` and `datatype` on a literal; and `.variables` on the array | SELECT |
50
50
  | N-Triples strings, one per triple, no trailing separator | CONSTRUCT, DESCRIBE |
51
51
  | a document in the format you asked for | `queryRdf` |
52
52
  | `{inserted, deleted, graphsCreated, graphsDropped}` | `update` |
53
+ | `{pending, result}`, the host fetching what is pending | `queryFederated` |
54
+ | the plan as JSON, with statistics from the run | `explain` |
55
+
56
+ A SELECT result carries **`.variables`**, the projected variables in order, as a property on the
57
+ array — so `result.length` and `for (const row of result)` keep working. The rows cannot carry
58
+ this: an unbound variable is absent from a row, so one unbound in *every* row is invisible, and
59
+ a result with no rows has no columns at all — while `head.vars` in the SPARQL results JSON
60
+ format must list every projected variable regardless. Without it a caller has to parse the
61
+ projection out of the query text.
62
+
63
+ For an explicit projection the order is the one you wrote. For **`SELECT *` the order is
64
+ alphabetical**, so `SELECT * WHERE { ?s ?p ?o }` names them `o`, `p`, `s`. SPARQL fixes no order
65
+ for `head.vars`, so both are conformant, but the second is not the order a reader expects. The
66
+ cause is one line in `spargebra`'s parser: it collects the in-scope variables in the order the
67
+ pattern mentions them and then calls `pv.sort()`, and the fact that the projection was `*` is
68
+ not kept in the parsed query — so this cannot be corrected here without guessing, because an
69
+ explicit `SELECT ?apple ?zebra` that happens to name every variable is indistinguishable from a
70
+ `*`, and reordering it would be worse than the problem. Fixing it means dropping that sort
71
+ upstream.
72
+
73
+ A literal's **`direction`** is its RDF 1.2 base direction, `"ltr"`, `"rtl"` or `""` — the same
74
+ "always present, empty when absent" convention as `language`, because a field that is sometimes
75
+ missing makes every reader check before it can compare.
76
+
77
+ **`explain` evaluates.** The results are drained and discarded before the plan is written,
78
+ because the statistics are gathered as rows flow through the operators. So it costs a full run,
79
+ and tells you what the run did rather than what the planner intended: every node carries its
80
+ own `number of results` and `duration in seconds`, and reading the counts from the bottom up
81
+ gives you the query's funnel. Until 0.20.0 the draining happened and the statistics did not
82
+ arrive — the evaluator was never told to compute them, so the plan came back as a tree of
83
+ operator names and the full run bought nothing.
53
84
 
54
85
  **SELECT returns terms, not strings, since 0.17.0.** They used to be N-Triples strings,
55
86
  which made every consumer parse term syntax to reach a value, and no RDF library in JS
@@ -138,6 +169,30 @@ objection does not transfer here, and not because a browser is safer — because
138
169
  cannot make a request at all**. There is nothing to point anywhere. The fetch is the host's, in
139
170
  the user's own browser, with the user's own network position and CORS between them.
140
171
 
172
+ ### The keys go with the question
173
+
174
+ A `SERVICE` is sent the keys it will be joined against, as a `VALUES` block. Without that, a
175
+ clause like
176
+
177
+ ```sparql
178
+ ?town owl:sameAs ?dbp .
179
+ SERVICE <https://dbpedia.org/sparql> { ?dbp dbo:populationTotal ?population }
180
+ ```
181
+
182
+ asks the endpoint for *every* population it holds and then joins locally — and an endpoint that
183
+ caps its answer, as DBpedia caps at ten thousand rows, will not have put the rows you wanted in
184
+ the ten thousand it chose. Measured: the query above returned nothing before, and one row after,
185
+ which is what Fuseki returns.
186
+
187
+ So `pending` reports a query with the keys already in it. Nothing is required of the host: it
188
+ POSTs what it is given, as before.
189
+
190
+ The keys come from evaluating the query's local part first, which is an extra evaluation per
191
+ pass. What is *not* pushed, because pushing too few keys would drop rows silently: a variable the
192
+ local part leaves unbound in any row, a blank node, and anything above 1024 distinct tuples. A
193
+ `SERVICE` whose keys come from another `SERVICE` is still sent unrestricted — the rounds below
194
+ are what resolve a chain.
195
+
141
196
  ### More than two rounds is normal
142
197
 
143
198
  A `SERVICE` whose pattern carries bindings from an earlier join only takes its final shape once
package/holos_wasm.d.ts CHANGED
@@ -30,6 +30,23 @@ export class Store {
30
30
  * and every JS RDF library can parse what comes back.
31
31
  */
32
32
  dump(format: string): string;
33
+ /**
34
+ * The query plan, as JSON, with the statistics from actually running it.
35
+ *
36
+ * HOLOS has had this since the CLI's `--explain`; it was simply not reachable from here,
37
+ * so a browser could run a query far faster than a server and still not say how.
38
+ *
39
+ * **It evaluates.** The results are drained and discarded, because an explanation
40
+ * serialised before the results are consumed reports zeroes for every operator — the
41
+ * statistics are gathered as rows flow through it. So this costs a full run and answers
42
+ * what that run did, rather than what the planner intended.
43
+ *
44
+ * # Errors
45
+ *
46
+ * As `query`, plus the case where the engine returns no explanation at all, which would
47
+ * mean the request for one was dropped on the way through.
48
+ */
49
+ explain(query: string, base?: string | null): string;
33
50
  /**
34
51
  * Load Turtle, which is the common case.
35
52
  */
package/holos_wasm.js CHANGED
@@ -80,6 +80,47 @@ class Store {
80
80
  wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
81
81
  }
82
82
  }
83
+ /**
84
+ * The query plan, as JSON, with the statistics from actually running it.
85
+ *
86
+ * HOLOS has had this since the CLI's `--explain`; it was simply not reachable from here,
87
+ * so a browser could run a query far faster than a server and still not say how.
88
+ *
89
+ * **It evaluates.** The results are drained and discarded, because an explanation
90
+ * serialised before the results are consumed reports zeroes for every operator — the
91
+ * statistics are gathered as rows flow through it. So this costs a full run and answers
92
+ * what that run did, rather than what the planner intended.
93
+ *
94
+ * # Errors
95
+ *
96
+ * As `query`, plus the case where the engine returns no explanation at all, which would
97
+ * mean the request for one was dropped on the way through.
98
+ * @param {string} query
99
+ * @param {string | null} [base]
100
+ * @returns {string}
101
+ */
102
+ explain(query, base) {
103
+ let deferred4_0;
104
+ let deferred4_1;
105
+ try {
106
+ const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
107
+ const len0 = WASM_VECTOR_LEN;
108
+ var ptr1 = isLikeNone(base) ? 0 : passStringToWasm0(base, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
109
+ var len1 = WASM_VECTOR_LEN;
110
+ const ret = wasm.store_explain(this.__wbg_ptr, ptr0, len0, ptr1, len1);
111
+ var ptr3 = ret[0];
112
+ var len3 = ret[1];
113
+ if (ret[3]) {
114
+ ptr3 = 0; len3 = 0;
115
+ throw takeFromExternrefTable0(ret[2]);
116
+ }
117
+ deferred4_0 = ptr3;
118
+ deferred4_1 = len3;
119
+ return getStringFromWasm0(ptr3, len3);
120
+ } finally {
121
+ wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
122
+ }
123
+ }
83
124
  /**
84
125
  * Load Turtle, which is the common case.
85
126
  * @param {string} text
Binary file
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "holos-wasm-node",
3
3
  "description": "WebAssembly bindings for the HOLOS RDF 1.2 store and SPARQL 1.2 engine (CommonJS, for Node and require())",
4
- "version": "0.18.0",
4
+ "version": "0.20.0",
5
5
  "license": "MIT OR Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",