holos-wasm-node 0.19.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
@@ -60,14 +60,27 @@ a result with no rows has no columns at all — while `head.vars` in the SPARQL
60
60
  format must list every projected variable regardless. Without it a caller has to parse the
61
61
  projection out of the query text.
62
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
+
63
73
  A literal's **`direction`** is its RDF 1.2 base direction, `"ltr"`, `"rtl"` or `""` — the same
64
74
  "always present, empty when absent" convention as `language`, because a field that is sometimes
65
75
  missing makes every reader check before it can compare.
66
76
 
67
77
  **`explain` evaluates.** The results are drained and discarded before the plan is written,
68
- because the statistics are gathered as rows flow through the operators — a plan serialised
69
- before that reports zeroes everywhere. So it costs a full run and tells you what the run did,
70
- not what the planner intended.
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.
71
84
 
72
85
  **SELECT returns terms, not strings, since 0.17.0.** They used to be N-Triples strings,
73
86
  which made every consumer parse term syntax to reach a value, and no RDF library in JS
@@ -156,6 +169,30 @@ objection does not transfer here, and not because a browser is safer — because
156
169
  cannot make a request at all**. There is nothing to point anywhere. The fetch is the host's, in
157
170
  the user's own browser, with the user's own network position and CORS between them.
158
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
+
159
196
  ### More than two rounds is normal
160
197
 
161
198
  A `SERVICE` whose pattern carries bindings from an earlier join only takes its final shape once
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.19.0",
4
+ "version": "0.20.0",
5
5
  "license": "MIT OR Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",