flowquery 1.0.66 → 1.0.68
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 +84 -1
- package/dist/compute/runner.d.ts +17 -2
- package/dist/compute/runner.d.ts.map +1 -1
- package/dist/compute/runner.js +15 -3
- package/dist/compute/runner.js.map +1 -1
- package/dist/flowquery.min.js +1 -1
- package/dist/graph/physical_node.d.ts.map +1 -1
- package/dist/graph/physical_node.js +5 -2
- package/dist/graph/physical_node.js.map +1 -1
- package/dist/graph/physical_relationship.d.ts.map +1 -1
- package/dist/graph/physical_relationship.js +5 -2
- package/dist/graph/physical_relationship.js.map +1 -1
- package/dist/index.browser.d.ts +2 -1
- package/dist/index.browser.d.ts.map +1 -1
- package/dist/index.browser.js.map +1 -1
- package/dist/index.node.d.ts +2 -1
- package/dist/index.node.d.ts.map +1 -1
- package/dist/index.node.js.map +1 -1
- package/dist/parsing/parser.d.ts.map +1 -1
- package/dist/parsing/parser.js.map +1 -1
- package/dist/parsing/statement_info_crawler.d.ts +216 -0
- package/dist/parsing/statement_info_crawler.d.ts.map +1 -0
- package/dist/parsing/statement_info_crawler.js +730 -0
- package/dist/parsing/statement_info_crawler.js.map +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -249,9 +249,92 @@ const runner = new FlowQuery("CREATE VIRTUAL (:X) AS { RETURN 1 AS id }; MATCH (
|
|
|
249
249
|
await runner.run();
|
|
250
250
|
console.log(runner.metadata);
|
|
251
251
|
// { virtual_nodes_created: 1, virtual_relationships_created: 0,
|
|
252
|
-
// virtual_nodes_deleted: 0, virtual_relationships_deleted: 0
|
|
252
|
+
// virtual_nodes_deleted: 0, virtual_relationships_deleted: 0,
|
|
253
|
+
// info: { node_labels: ["X"], relationship_types: [], sources: [], ... } }
|
|
253
254
|
```
|
|
254
255
|
|
|
256
|
+
#### Statement Info: Labels, Properties, and Source Lineage
|
|
257
|
+
|
|
258
|
+
`metadata.info` carries a `StatementInfo` describing the _structure_ the
|
|
259
|
+
query touches — independent of execution. It captures:
|
|
260
|
+
|
|
261
|
+
- The node labels and relationship types referenced.
|
|
262
|
+
- The data sources backing the underlying virtual definitions.
|
|
263
|
+
- The node/relationship properties **consumed** by the query —
|
|
264
|
+
`alias.prop` accesses anywhere in `MATCH`, `WHERE`, `WITH`, `RETURN`,
|
|
265
|
+
`ORDER BY`, or function arguments, plus inline pattern properties
|
|
266
|
+
like `(u:User {id: 'rick.o'})`.
|
|
267
|
+
- The properties **declared** by each virtual's `RETURN` clause via
|
|
268
|
+
`info.declared`, so you can validate that a query references only
|
|
269
|
+
declared properties.
|
|
270
|
+
- Literal values supplied for properties at the call site via
|
|
271
|
+
`info.nodes[Label].literal_values` — collected from inline pattern
|
|
272
|
+
properties and from equality / `IN` predicates such as
|
|
273
|
+
`WHERE u.id = 'rick.o'` or `WHERE u.id IN ['a', 'b']`.
|
|
274
|
+
|
|
275
|
+
This is useful for governance, lineage UIs, query-cost estimation, schema
|
|
276
|
+
validation, or routing decisions before the query runs.
|
|
277
|
+
|
|
278
|
+
The same `StatementInfoCrawler` can also be used directly on any parsed
|
|
279
|
+
AST without going through a `Runner`:
|
|
280
|
+
|
|
281
|
+
```javascript
|
|
282
|
+
import { StatementInfoCrawler } from "flowquery";
|
|
283
|
+
|
|
284
|
+
const crawler = new StatementInfoCrawler();
|
|
285
|
+
const info = crawler.crawl(parsedAst);
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
For end-to-end lineage from a property to its data source, use the
|
|
289
|
+
per-entity `nodes` and `relationships` maps:
|
|
290
|
+
|
|
291
|
+
```javascript
|
|
292
|
+
const runner = new FlowQuery(`
|
|
293
|
+
CREATE VIRTUAL (:City) AS {
|
|
294
|
+
LOAD JSON FROM "https://example.com/cities" AS c
|
|
295
|
+
RETURN c.id AS id, c.name AS name, c.country AS country
|
|
296
|
+
};
|
|
297
|
+
CREATE VIRTUAL (:City)-[:FLIGHT]-(:City) AS {
|
|
298
|
+
LOAD JSON FROM "https://example.com/flights" AS f
|
|
299
|
+
RETURN f.left_id AS left_id, f.right_id AS right_id, f.airline AS airline
|
|
300
|
+
};
|
|
301
|
+
MATCH (a:City {name: 'NYC'})-[r:FLIGHT]->(b:City)
|
|
302
|
+
WHERE b.country IN ['US', 'CA']
|
|
303
|
+
RETURN a.name AS origin, b.name AS destination, r.airline AS airline
|
|
304
|
+
`);
|
|
305
|
+
const { info } = runner.metadata;
|
|
306
|
+
|
|
307
|
+
console.log(info.nodes);
|
|
308
|
+
// {
|
|
309
|
+
// City: {
|
|
310
|
+
// properties: ["country", "name"],
|
|
311
|
+
// sources: ["https://example.com/cities"],
|
|
312
|
+
// literal_values: { country: ["US", "CA"], name: ["NYC"] }
|
|
313
|
+
// }
|
|
314
|
+
// }
|
|
315
|
+
console.log(info.relationships);
|
|
316
|
+
// {
|
|
317
|
+
// FLIGHT: {
|
|
318
|
+
// properties: ["airline"],
|
|
319
|
+
// sources: ["https://example.com/flights"],
|
|
320
|
+
// literal_values: {}
|
|
321
|
+
// }
|
|
322
|
+
// }
|
|
323
|
+
console.log(info.declared.nodes.City);
|
|
324
|
+
// { properties: ["country", "id", "name"], sources: ["https://example.com/cities"] }
|
|
325
|
+
console.log(info.sources);
|
|
326
|
+
// ["https://example.com/cities", "https://example.com/flights"]
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
`StatementInfo` resolves sources and declared schemas for **any** virtual
|
|
330
|
+
the query touches — both inline `CREATE VIRTUAL` clauses and
|
|
331
|
+
previously-registered virtuals reached via `MATCH` or `DELETE`. The flat
|
|
332
|
+
`node_labels`, `relationship_types`, `sources`, `node_properties`, and
|
|
333
|
+
`relationship_properties` fields stay in sync with the per-entity `nodes` /
|
|
334
|
+
`relationships` maps and are convenient for quick aggregate checks. Only
|
|
335
|
+
purely literal AST subtrees end up in `literal_values` — values that depend
|
|
336
|
+
on parameters, references, f-strings, or subqueries are skipped.
|
|
337
|
+
|
|
255
338
|
### WHERE Clause
|
|
256
339
|
|
|
257
340
|
Filters rows based on conditions. Supports the following operators:
|
package/dist/compute/runner.d.ts
CHANGED
|
@@ -1,12 +1,24 @@
|
|
|
1
1
|
import ASTNode from "../parsing/ast_node";
|
|
2
|
+
import { StatementInfo } from "../parsing/statement_info_crawler";
|
|
3
|
+
export type { StatementInfo } from "../parsing/statement_info_crawler";
|
|
2
4
|
/**
|
|
3
5
|
* Metadata about the operations performed by a Runner execution.
|
|
6
|
+
*
|
|
7
|
+
* The four counters track CREATE/DELETE VIRTUAL operations. The optional
|
|
8
|
+
* `info` field carries deeper structural information about the statement(s)
|
|
9
|
+
* — labels, relationship types, sources, and properties — produced by
|
|
10
|
+
* {@link StatementInfoCrawler}.
|
|
4
11
|
*/
|
|
5
12
|
export interface RunnerMetadata {
|
|
6
13
|
virtual_nodes_created: number;
|
|
7
14
|
virtual_relationships_created: number;
|
|
8
15
|
virtual_nodes_deleted: number;
|
|
9
16
|
virtual_relationships_deleted: number;
|
|
17
|
+
/**
|
|
18
|
+
* Optional structural info produced by walking the parsed statement(s).
|
|
19
|
+
* Populated by the Runner whenever metadata is requested.
|
|
20
|
+
*/
|
|
21
|
+
info?: StatementInfo;
|
|
10
22
|
}
|
|
11
23
|
/**
|
|
12
24
|
* Executes a FlowQuery statement and retrieves the results.
|
|
@@ -42,7 +54,9 @@ declare class Runner {
|
|
|
42
54
|
constructor(statement?: string | null, ast?: ASTNode | null, args?: Record<string, any> | null);
|
|
43
55
|
private static toStatement;
|
|
44
56
|
/**
|
|
45
|
-
* Walks all statement ASTs to count CREATE/DELETE operations
|
|
57
|
+
* Walks all statement ASTs to count CREATE/DELETE operations and to
|
|
58
|
+
* crawl the statements for richer structural info via
|
|
59
|
+
* {@link StatementInfoCrawler}.
|
|
46
60
|
*/
|
|
47
61
|
private computeMetadata;
|
|
48
62
|
/**
|
|
@@ -68,7 +82,8 @@ declare class Runner {
|
|
|
68
82
|
/**
|
|
69
83
|
* Gets metadata about the operations in this query.
|
|
70
84
|
*
|
|
71
|
-
*
|
|
85
|
+
* Returns a deep copy so callers can mutate the result without affecting
|
|
86
|
+
* subsequent reads.
|
|
72
87
|
*/
|
|
73
88
|
get metadata(): RunnerMetadata;
|
|
74
89
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":"AAEA,OAAO,OAAO,MAAM,qBAAqB,CAAC;
|
|
1
|
+
{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":"AAEA,OAAO,OAAO,MAAM,qBAAqB,CAAC;AAQ1C,OAA6B,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAExF,YAAY,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,6BAA6B,EAAE,MAAM,CAAC;IACtC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,6BAA6B,EAAE,MAAM,CAAC;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC;CACxB;AAQD;;;;;;;;;;;;;;;;;GAiBG;AACH,cAAM,MAAM;IACR,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,WAAW,CAAU;IAC7B,OAAO,CAAC,SAAS,CAAiB;IAElC;;;;;;;OAOG;gBAEC,SAAS,GAAE,MAAM,GAAG,IAAW,EAC/B,GAAG,GAAE,OAAO,GAAG,IAAW,EAC1B,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAW;IAqB3C,OAAO,CAAC,MAAM,CAAC,WAAW;IAQ1B;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAqBvB;;;;;OAKG;IACU,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBjC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAetB;;;;OAIG;IACH,IAAW,OAAO,IAAI,GAAG,CAExB;IAED;;;;;OAKG;IACH,IAAW,QAAQ,IAAI,cAAc,CASpC;CACJ;AAED,eAAe,MAAM,CAAC"}
|
package/dist/compute/runner.js
CHANGED
|
@@ -20,6 +20,7 @@ const create_relationship_1 = __importDefault(require("../parsing/operations/cre
|
|
|
20
20
|
const delete_node_1 = __importDefault(require("../parsing/operations/delete_node"));
|
|
21
21
|
const delete_relationship_1 = __importDefault(require("../parsing/operations/delete_relationship"));
|
|
22
22
|
const parser_1 = __importDefault(require("../parsing/parser"));
|
|
23
|
+
const statement_info_crawler_1 = __importDefault(require("../parsing/statement_info_crawler"));
|
|
23
24
|
/**
|
|
24
25
|
* Executes a FlowQuery statement and retrieves the results.
|
|
25
26
|
*
|
|
@@ -71,7 +72,9 @@ class Runner {
|
|
|
71
72
|
};
|
|
72
73
|
}
|
|
73
74
|
/**
|
|
74
|
-
* Walks all statement ASTs to count CREATE/DELETE operations
|
|
75
|
+
* Walks all statement ASTs to count CREATE/DELETE operations and to
|
|
76
|
+
* crawl the statements for richer structural info via
|
|
77
|
+
* {@link StatementInfoCrawler}.
|
|
75
78
|
*/
|
|
76
79
|
computeMetadata() {
|
|
77
80
|
const metadata = {
|
|
@@ -94,6 +97,7 @@ class Runner {
|
|
|
94
97
|
op = op.next;
|
|
95
98
|
}
|
|
96
99
|
}
|
|
100
|
+
metadata.info = new statement_info_crawler_1.default().crawl(this._statements.map((s) => s.ast));
|
|
97
101
|
return metadata;
|
|
98
102
|
}
|
|
99
103
|
/**
|
|
@@ -156,10 +160,18 @@ class Runner {
|
|
|
156
160
|
/**
|
|
157
161
|
* Gets metadata about the operations in this query.
|
|
158
162
|
*
|
|
159
|
-
*
|
|
163
|
+
* Returns a deep copy so callers can mutate the result without affecting
|
|
164
|
+
* subsequent reads.
|
|
160
165
|
*/
|
|
161
166
|
get metadata() {
|
|
162
|
-
|
|
167
|
+
const m = this._metadata;
|
|
168
|
+
return {
|
|
169
|
+
virtual_nodes_created: m.virtual_nodes_created,
|
|
170
|
+
virtual_relationships_created: m.virtual_relationships_created,
|
|
171
|
+
virtual_nodes_deleted: m.virtual_nodes_deleted,
|
|
172
|
+
virtual_relationships_deleted: m.virtual_relationships_deleted,
|
|
173
|
+
info: m.info ? statement_info_crawler_1.default.clone(m.info) : undefined,
|
|
174
|
+
};
|
|
163
175
|
}
|
|
164
176
|
}
|
|
165
177
|
exports.default = Runner;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":";;;;;;;;;;;;;;AAAA,qEAA4C;AAC5C,2EAAkD;AAElD,qGAA4E;AAC5E,oFAA2D;AAC3D,oGAA2E;AAC3E,oFAA2D;AAC3D,oGAA2E;AAE3E,+DAAuC;
|
|
1
|
+
{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":"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"}
|