holos-wasm 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 +56 -1
- package/holos_wasm.d.ts +17 -0
- package/holos_wasm_bg.js +41 -0
- package/holos_wasm_bg.wasm +0 -0
- package/package.json +1 -1
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_bg.js
CHANGED
|
@@ -78,6 +78,47 @@ export class Store {
|
|
|
78
78
|
wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
|
|
79
79
|
}
|
|
80
80
|
}
|
|
81
|
+
/**
|
|
82
|
+
* The query plan, as JSON, with the statistics from actually running it.
|
|
83
|
+
*
|
|
84
|
+
* HOLOS has had this since the CLI's `--explain`; it was simply not reachable from here,
|
|
85
|
+
* so a browser could run a query far faster than a server and still not say how.
|
|
86
|
+
*
|
|
87
|
+
* **It evaluates.** The results are drained and discarded, because an explanation
|
|
88
|
+
* serialised before the results are consumed reports zeroes for every operator — the
|
|
89
|
+
* statistics are gathered as rows flow through it. So this costs a full run and answers
|
|
90
|
+
* what that run did, rather than what the planner intended.
|
|
91
|
+
*
|
|
92
|
+
* # Errors
|
|
93
|
+
*
|
|
94
|
+
* As `query`, plus the case where the engine returns no explanation at all, which would
|
|
95
|
+
* mean the request for one was dropped on the way through.
|
|
96
|
+
* @param {string} query
|
|
97
|
+
* @param {string | null} [base]
|
|
98
|
+
* @returns {string}
|
|
99
|
+
*/
|
|
100
|
+
explain(query, base) {
|
|
101
|
+
let deferred4_0;
|
|
102
|
+
let deferred4_1;
|
|
103
|
+
try {
|
|
104
|
+
const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
|
|
105
|
+
const len0 = WASM_VECTOR_LEN;
|
|
106
|
+
var ptr1 = isLikeNone(base) ? 0 : passStringToWasm0(base, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
|
|
107
|
+
var len1 = WASM_VECTOR_LEN;
|
|
108
|
+
const ret = wasm.store_explain(this.__wbg_ptr, ptr0, len0, ptr1, len1);
|
|
109
|
+
var ptr3 = ret[0];
|
|
110
|
+
var len3 = ret[1];
|
|
111
|
+
if (ret[3]) {
|
|
112
|
+
ptr3 = 0; len3 = 0;
|
|
113
|
+
throw takeFromExternrefTable0(ret[2]);
|
|
114
|
+
}
|
|
115
|
+
deferred4_0 = ptr3;
|
|
116
|
+
deferred4_1 = len3;
|
|
117
|
+
return getStringFromWasm0(ptr3, len3);
|
|
118
|
+
} finally {
|
|
119
|
+
wasm.__wbindgen_free(deferred4_0, deferred4_1, 1);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
81
122
|
/**
|
|
82
123
|
* Load Turtle, which is the common case.
|
|
83
124
|
* @param {string} text
|
package/holos_wasm_bg.wasm
CHANGED
|
Binary file
|
package/package.json
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
"name": "holos-wasm",
|
|
3
3
|
"type": "module",
|
|
4
4
|
"description": "WebAssembly bindings for the HOLOS RDF 1.2 store and SPARQL 1.2 engine (ESM, for bundlers)",
|
|
5
|
-
"version": "0.
|
|
5
|
+
"version": "0.20.0",
|
|
6
6
|
"license": "MIT OR Apache-2.0",
|
|
7
7
|
"repository": {
|
|
8
8
|
"type": "git",
|