flowquery 1.0.70 → 1.0.71
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 +456 -103
- package/dist/compute/provenance.d.ts +201 -0
- package/dist/compute/provenance.d.ts.map +1 -0
- package/dist/compute/provenance.js +216 -0
- package/dist/compute/provenance.js.map +1 -0
- package/dist/compute/runner.d.ts +196 -3
- package/dist/compute/runner.d.ts.map +1 -1
- package/dist/compute/runner.js +283 -2
- package/dist/compute/runner.js.map +1 -1
- package/dist/flowquery.min.js +1 -1
- package/dist/graph/bindings.d.ts.map +1 -1
- package/dist/graph/bindings.js +15 -1
- package/dist/graph/bindings.js.map +1 -1
- package/dist/graph/data_cache.d.ts +4 -0
- package/dist/graph/data_cache.d.ts.map +1 -1
- package/dist/graph/data_cache.js +15 -3
- package/dist/graph/data_cache.js.map +1 -1
- package/dist/graph/data_resolver.d.ts.map +1 -1
- package/dist/graph/data_resolver.js +23 -4
- package/dist/graph/data_resolver.js.map +1 -1
- package/dist/graph/physical_node.d.ts +4 -8
- package/dist/graph/physical_node.d.ts.map +1 -1
- package/dist/graph/physical_node.js +14 -85
- package/dist/graph/physical_node.js.map +1 -1
- package/dist/graph/physical_relationship.d.ts +4 -8
- package/dist/graph/physical_relationship.d.ts.map +1 -1
- package/dist/graph/physical_relationship.js +14 -85
- package/dist/graph/physical_relationship.js.map +1 -1
- package/dist/graph/relationship_match_collector.d.ts.map +1 -1
- package/dist/graph/relationship_match_collector.js +9 -0
- package/dist/graph/relationship_match_collector.js.map +1 -1
- package/dist/graph/virtual_sources.d.ts +8 -0
- package/dist/graph/virtual_sources.d.ts.map +1 -0
- package/dist/graph/virtual_sources.js +31 -0
- package/dist/graph/virtual_sources.js.map +1 -0
- package/dist/graph/virtual_statement.d.ts +41 -0
- package/dist/graph/virtual_statement.d.ts.map +1 -0
- package/dist/graph/virtual_statement.js +143 -0
- package/dist/graph/virtual_statement.js.map +1 -0
- package/dist/index.browser.d.ts +3 -3
- package/dist/index.browser.d.ts.map +1 -1
- package/dist/index.browser.js.map +1 -1
- package/dist/index.node.d.ts +3 -3
- package/dist/index.node.d.ts.map +1 -1
- package/dist/index.node.js.map +1 -1
- package/dist/parsing/operations/aggregated_return.d.ts +10 -0
- package/dist/parsing/operations/aggregated_return.d.ts.map +1 -1
- package/dist/parsing/operations/aggregated_return.js +56 -3
- package/dist/parsing/operations/aggregated_return.js.map +1 -1
- package/dist/parsing/operations/aggregated_with.d.ts +20 -0
- package/dist/parsing/operations/aggregated_with.d.ts.map +1 -1
- package/dist/parsing/operations/aggregated_with.js +33 -1
- package/dist/parsing/operations/aggregated_with.js.map +1 -1
- package/dist/parsing/operations/group_by.d.ts +32 -0
- package/dist/parsing/operations/group_by.d.ts.map +1 -1
- package/dist/parsing/operations/group_by.js +103 -0
- package/dist/parsing/operations/group_by.js.map +1 -1
- package/dist/parsing/operations/let.d.ts.map +1 -1
- package/dist/parsing/operations/let.js +53 -0
- package/dist/parsing/operations/let.js.map +1 -1
- package/dist/parsing/operations/load.d.ts +20 -0
- package/dist/parsing/operations/load.d.ts.map +1 -1
- package/dist/parsing/operations/load.js +71 -0
- package/dist/parsing/operations/load.js.map +1 -1
- package/dist/parsing/operations/order_by.d.ts +6 -0
- package/dist/parsing/operations/order_by.d.ts.map +1 -1
- package/dist/parsing/operations/order_by.js +10 -1
- package/dist/parsing/operations/order_by.js.map +1 -1
- package/dist/parsing/operations/return.d.ts +34 -0
- package/dist/parsing/operations/return.d.ts.map +1 -1
- package/dist/parsing/operations/return.js +95 -2
- package/dist/parsing/operations/return.js.map +1 -1
- package/dist/parsing/operations/union.d.ts +19 -2
- package/dist/parsing/operations/union.d.ts.map +1 -1
- package/dist/parsing/operations/union.js +47 -11
- package/dist/parsing/operations/union.js.map +1 -1
- package/dist/parsing/operations/union_all.d.ts +5 -1
- package/dist/parsing/operations/union_all.d.ts.map +1 -1
- package/dist/parsing/operations/union_all.js +8 -2
- package/dist/parsing/operations/union_all.js.map +1 -1
- package/dist/parsing/statement_info_crawler.d.ts +106 -0
- package/dist/parsing/statement_info_crawler.d.ts.map +1 -1
- package/dist/parsing/statement_info_crawler.js +231 -12
- package/dist/parsing/statement_info_crawler.js.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
import Node from "../graph/node";
|
|
2
|
+
import Relationship from "../graph/relationship";
|
|
3
|
+
/**
|
|
4
|
+
* One observation that a particular alias was bound to a particular node id
|
|
5
|
+
* while a result row was being projected. For non-aggregate rows there is
|
|
6
|
+
* exactly one `NodeBinding` per registered node slot; aggregate rows may
|
|
7
|
+
* carry multiple observations under the same alias when distinct ids fed the
|
|
8
|
+
* group.
|
|
9
|
+
*
|
|
10
|
+
* `id` preserves the original scalar type from the underlying record (string,
|
|
11
|
+
* number, etc.). `id === null` indicates an OPTIONAL MATCH miss.
|
|
12
|
+
*/
|
|
13
|
+
export interface NodeBinding {
|
|
14
|
+
/** The node identifier from the query (e.g. `a`), or `null` if anonymous. */
|
|
15
|
+
alias: string | null;
|
|
16
|
+
/** The matched label from the query (the first declared label), or `null`. */
|
|
17
|
+
label: string | null;
|
|
18
|
+
/** The concrete `id` value of the matched node, preserving scalar type. */
|
|
19
|
+
id: any;
|
|
20
|
+
/**
|
|
21
|
+
* Shallow snapshot of the matched record's property values (excluding
|
|
22
|
+
* `id` and internal `_label`). Present whenever the runner was
|
|
23
|
+
* constructed with `{ provenance: true }`.
|
|
24
|
+
*/
|
|
25
|
+
properties?: Record<string, any>;
|
|
26
|
+
/**
|
|
27
|
+
* When the matched node came from a virtual
|
|
28
|
+
* `CREATE VIRTUAL (:X) AS { ... }` sub-query, this is the inner
|
|
29
|
+
* runner's `RowProvenance` row that produced the record. Omitted
|
|
30
|
+
* when the source is not a virtual.
|
|
31
|
+
*/
|
|
32
|
+
source?: RowProvenance;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* One traversed edge in a relationship binding. Variable-length matches
|
|
36
|
+
* (`[:T*m..n]`) contribute multiple hops; single-hop matches contribute one.
|
|
37
|
+
*/
|
|
38
|
+
export interface RelationshipHop {
|
|
39
|
+
left_id: any;
|
|
40
|
+
right_id: any;
|
|
41
|
+
/** Resolved relationship type (may differ from the declared type when a
|
|
42
|
+
* virtual relationship spans multiple underlying types). */
|
|
43
|
+
type: string;
|
|
44
|
+
/**
|
|
45
|
+
* Shallow snapshot of the relationship record's property values.
|
|
46
|
+
* Present whenever the runner was constructed with
|
|
47
|
+
* `{ provenance: true }`.
|
|
48
|
+
*/
|
|
49
|
+
properties?: Record<string, any>;
|
|
50
|
+
/**
|
|
51
|
+
* When the traversed edge came from a virtual
|
|
52
|
+
* relationship's inner sub-query, this is the inner runner's row
|
|
53
|
+
* provenance for the contributing record. Omitted otherwise.
|
|
54
|
+
*/
|
|
55
|
+
source?: RowProvenance;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* One observation that a particular relationship alias was bound to a
|
|
59
|
+
* concrete path of one or more hops while a result row was being projected.
|
|
60
|
+
*/
|
|
61
|
+
export interface RelationshipBinding {
|
|
62
|
+
/** The relationship identifier from the query (e.g. `r`), or `null`. */
|
|
63
|
+
alias: string | null;
|
|
64
|
+
/** The declared relationship type from the query, or `null` when omitted. */
|
|
65
|
+
type: string | null;
|
|
66
|
+
/** The traversed edges in path order. */
|
|
67
|
+
hops: RelationshipHop[];
|
|
68
|
+
/**
|
|
69
|
+
* The ordered chain of node ids visited along the relationship match:
|
|
70
|
+
* `[hops[0].left_id, ...hops.map(h => h.right_id)]`. Always present.
|
|
71
|
+
* Empty for OPTIONAL-MATCH misses and zero-hop variable-length matches.
|
|
72
|
+
*/
|
|
73
|
+
path: any[];
|
|
74
|
+
}
|
|
75
|
+
/**
|
|
76
|
+
* One observation that a particular `LOAD` operation contributed a row
|
|
77
|
+
* to the projected result. Records the resolved source name and,
|
|
78
|
+
* recursively, the inner provenance that backed the row when the
|
|
79
|
+
* source was a `LET`-bound dataset.
|
|
80
|
+
*/
|
|
81
|
+
export interface DataSourceBinding {
|
|
82
|
+
/**
|
|
83
|
+
* The resolved source identifier: a URL, file URI, async-function
|
|
84
|
+
* name, or `let://<name>` reference for a `LET`-bound dataset.
|
|
85
|
+
*/
|
|
86
|
+
source: string;
|
|
87
|
+
/**
|
|
88
|
+
* When the row came from a `LET`-backed array whose inner runner
|
|
89
|
+
* was executed with provenance, this is the inner runner's
|
|
90
|
+
* `RowProvenance` row for the loaded record. Provides recursive
|
|
91
|
+
* traceability back through the `LET`'s own sub-query (which may
|
|
92
|
+
* itself include `LOAD` operations). Omitted otherwise.
|
|
93
|
+
*/
|
|
94
|
+
source_provenance?: RowProvenance;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* One flat slice of bindings - either a single non-aggregate row's
|
|
98
|
+
* contribution, or one input row's contribution to an aggregate group.
|
|
99
|
+
* Sources (`ProvenanceSource.snapshot`) and the entries in
|
|
100
|
+
* `RowProvenance.rows` are all `RowSegment`s.
|
|
101
|
+
*/
|
|
102
|
+
export interface RowSegment {
|
|
103
|
+
nodes: NodeBinding[];
|
|
104
|
+
relationships: RelationshipBinding[];
|
|
105
|
+
/**
|
|
106
|
+
* Data sources consumed while projecting this row. Populated when
|
|
107
|
+
* the pipeline includes a `LOAD` operation: one entry per emitted
|
|
108
|
+
* `Load` record. Each entry's `source` is the URL / file URI /
|
|
109
|
+
* async-function name / `let://name` reference; `source_provenance`
|
|
110
|
+
* is the inner `RowProvenance` row when the source was a
|
|
111
|
+
* `LET`-bound dataset. Omitted when the segment has no Load
|
|
112
|
+
* contributions.
|
|
113
|
+
*/
|
|
114
|
+
data_sources?: DataSourceBinding[];
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Row-level lineage aligned by index with `Runner.results`. Extends a
|
|
118
|
+
* single segment (the union of contributing bindings) with `rows`, the
|
|
119
|
+
* ordered per-input-row segments. For non-aggregate rows `rows.length`
|
|
120
|
+
* is 1; for aggregates it equals the number of input rows that fed the
|
|
121
|
+
* group, so `result.collectField[k]` aligns positionally with
|
|
122
|
+
* `provenance.rows[k]`.
|
|
123
|
+
*/
|
|
124
|
+
export interface RowProvenance extends RowSegment {
|
|
125
|
+
rows: RowSegment[];
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Anything that can produce a `RowSegment` for the row currently being
|
|
129
|
+
* emitted. Two implementations exist today:
|
|
130
|
+
*
|
|
131
|
+
* - {@link ProvenanceSites} — snapshots the live bindings of a MATCH's
|
|
132
|
+
* `Node` / `Relationship` slots at the moment of the emit.
|
|
133
|
+
* - `AggregatedWith` (in `aggregated_with.ts`) — replays the pre-computed
|
|
134
|
+
* segment of the group it is currently flushing downstream.
|
|
135
|
+
*
|
|
136
|
+
* The terminal `Return` (and intermediate `AggregatedWith` /
|
|
137
|
+
* `AggregatedReturn` operations) iterate their registered sources per row
|
|
138
|
+
* and concatenate the segments into a single `RowSegment`.
|
|
139
|
+
*/
|
|
140
|
+
export interface ProvenanceSource {
|
|
141
|
+
snapshot(): RowSegment;
|
|
142
|
+
}
|
|
143
|
+
/**
|
|
144
|
+
* Concatenate one segment into a destination segment. Lives here so the
|
|
145
|
+
* merge order stays consistent across consumers (`Return`, `GroupBy`,
|
|
146
|
+
* `AggregatedWith`).
|
|
147
|
+
*/
|
|
148
|
+
export declare function mergeProvenanceSegment(into: RowSegment, segment: RowSegment): void;
|
|
149
|
+
/**
|
|
150
|
+
* Holds the set of `Node` and `Relationship` slots discovered in a query's
|
|
151
|
+
* MATCH operations. These are stable references; their live state is read
|
|
152
|
+
* synchronously on each `snapshot()` call to capture the bindings active at
|
|
153
|
+
* that moment.
|
|
154
|
+
*
|
|
155
|
+
* The collector is opt-in via the `provenance` Runner option and zero-cost
|
|
156
|
+
* when disabled.
|
|
157
|
+
*/
|
|
158
|
+
export declare class ProvenanceSites {
|
|
159
|
+
readonly nodes: Node[];
|
|
160
|
+
readonly relationships: Relationship[];
|
|
161
|
+
private readonly _seenNodeIdentifiers;
|
|
162
|
+
private readonly _seenRelationshipIdentifiers;
|
|
163
|
+
private _captureProperties;
|
|
164
|
+
/**
|
|
165
|
+
* Enable property-level capture for snapshots produced by this collector.
|
|
166
|
+
* Set by the Runner when constructed with `{ provenance: true }`.
|
|
167
|
+
*/
|
|
168
|
+
set captureProperties(value: boolean);
|
|
169
|
+
/**
|
|
170
|
+
* Register a node slot. `NodeReference`s (re-bindings of a previously
|
|
171
|
+
* matched identifier) and duplicate named identifiers are skipped so the
|
|
172
|
+
* same alias does not produce multiple bindings.
|
|
173
|
+
*/
|
|
174
|
+
addNode(node: Node): void;
|
|
175
|
+
/**
|
|
176
|
+
* Register a relationship slot. `RelationshipReference`s and duplicate
|
|
177
|
+
* named identifiers are skipped. Anonymous relationships are always
|
|
178
|
+
* added since each represents an independent traversal slot.
|
|
179
|
+
*/
|
|
180
|
+
addRelationship(rel: Relationship): void;
|
|
181
|
+
get isEmpty(): boolean;
|
|
182
|
+
/**
|
|
183
|
+
* Capture the currently-bound id / hop values for every registered slot.
|
|
184
|
+
* Returns `null` for ids of slots that are not currently matched (e.g.
|
|
185
|
+
* OPTIONAL MATCH misses).
|
|
186
|
+
*/
|
|
187
|
+
snapshot(): RowSegment;
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Stable canonical key for deduplicating a `NodeBinding` within an aggregate
|
|
191
|
+
* group. Uses `JSON.stringify` to preserve scalar type distinctions
|
|
192
|
+
* (`1` vs `"1"`).
|
|
193
|
+
*/
|
|
194
|
+
export declare function nodeBindingKey(b: NodeBinding): string;
|
|
195
|
+
/**
|
|
196
|
+
* Stable canonical key for deduplicating a `RelationshipBinding` within an
|
|
197
|
+
* aggregate group. Includes every hop so variable-length paths with the
|
|
198
|
+
* same alias but different traversals are treated as distinct.
|
|
199
|
+
*/
|
|
200
|
+
export declare function relationshipBindingKey(b: RelationshipBinding): string;
|
|
201
|
+
//# sourceMappingURL=provenance.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/compute/provenance.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,eAAe,CAAC;AAEjC,OAAO,YAAY,MAAM,uBAAuB,CAAC;AAIjD;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IACxB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2EAA2E;IAC3E,EAAE,EAAE,GAAG,CAAC;IACR;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,GAAG,CAAC;IACb,QAAQ,EAAE,GAAG,CAAC;IACd;iEAC6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAChC,wEAAwE;IACxE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,yCAAyC;IACzC,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB;;;;OAIG;IACH,IAAI,EAAE,GAAG,EAAE,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC9B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,aAAa,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACvB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,iBAAiB,EAAE,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC7C,IAAI,EAAE,UAAU,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,IAAI,UAAU,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI,CAOlF;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IACxB,SAAgB,KAAK,EAAE,IAAI,EAAE,CAAM;IACnC,SAAgB,aAAa,EAAE,YAAY,EAAE,CAAM;IACnD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA0B;IAC/D,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAA0B;IACvE,OAAO,CAAC,kBAAkB,CAAkB;IAE5C;;;OAGG;IACH,IAAW,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAE1C;IAED;;;;OAIG;IACI,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAUhC;;;;OAIG;IACI,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAU/C,IAAW,OAAO,IAAI,OAAO,CAE5B;IAED;;;;OAIG;IACI,QAAQ,IAAI,UAAU;CAqDhC;AA8CD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAOrE"}
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
exports.ProvenanceSites = void 0;
|
|
7
|
+
exports.mergeProvenanceSegment = mergeProvenanceSegment;
|
|
8
|
+
exports.nodeBindingKey = nodeBindingKey;
|
|
9
|
+
exports.relationshipBindingKey = relationshipBindingKey;
|
|
10
|
+
const node_reference_1 = __importDefault(require("../graph/node_reference"));
|
|
11
|
+
const relationship_reference_1 = __importDefault(require("../graph/relationship_reference"));
|
|
12
|
+
const virtual_sources_1 = require("../graph/virtual_sources");
|
|
13
|
+
/**
|
|
14
|
+
* Concatenate one segment into a destination segment. Lives here so the
|
|
15
|
+
* merge order stays consistent across consumers (`Return`, `GroupBy`,
|
|
16
|
+
* `AggregatedWith`).
|
|
17
|
+
*/
|
|
18
|
+
function mergeProvenanceSegment(into, segment) {
|
|
19
|
+
for (const n of segment.nodes)
|
|
20
|
+
into.nodes.push(n);
|
|
21
|
+
for (const r of segment.relationships)
|
|
22
|
+
into.relationships.push(r);
|
|
23
|
+
if (segment.data_sources !== undefined && segment.data_sources.length > 0) {
|
|
24
|
+
if (into.data_sources === undefined)
|
|
25
|
+
into.data_sources = [];
|
|
26
|
+
for (const d of segment.data_sources)
|
|
27
|
+
into.data_sources.push(d);
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Holds the set of `Node` and `Relationship` slots discovered in a query's
|
|
32
|
+
* MATCH operations. These are stable references; their live state is read
|
|
33
|
+
* synchronously on each `snapshot()` call to capture the bindings active at
|
|
34
|
+
* that moment.
|
|
35
|
+
*
|
|
36
|
+
* The collector is opt-in via the `provenance` Runner option and zero-cost
|
|
37
|
+
* when disabled.
|
|
38
|
+
*/
|
|
39
|
+
class ProvenanceSites {
|
|
40
|
+
constructor() {
|
|
41
|
+
this.nodes = [];
|
|
42
|
+
this.relationships = [];
|
|
43
|
+
this._seenNodeIdentifiers = new Set();
|
|
44
|
+
this._seenRelationshipIdentifiers = new Set();
|
|
45
|
+
this._captureProperties = false;
|
|
46
|
+
}
|
|
47
|
+
/**
|
|
48
|
+
* Enable property-level capture for snapshots produced by this collector.
|
|
49
|
+
* Set by the Runner when constructed with `{ provenance: true }`.
|
|
50
|
+
*/
|
|
51
|
+
set captureProperties(value) {
|
|
52
|
+
this._captureProperties = value;
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* Register a node slot. `NodeReference`s (re-bindings of a previously
|
|
56
|
+
* matched identifier) and duplicate named identifiers are skipped so the
|
|
57
|
+
* same alias does not produce multiple bindings.
|
|
58
|
+
*/
|
|
59
|
+
addNode(node) {
|
|
60
|
+
if (node instanceof node_reference_1.default)
|
|
61
|
+
return;
|
|
62
|
+
const id = node.identifier;
|
|
63
|
+
if (id !== null) {
|
|
64
|
+
if (this._seenNodeIdentifiers.has(id))
|
|
65
|
+
return;
|
|
66
|
+
this._seenNodeIdentifiers.add(id);
|
|
67
|
+
}
|
|
68
|
+
this.nodes.push(node);
|
|
69
|
+
}
|
|
70
|
+
/**
|
|
71
|
+
* Register a relationship slot. `RelationshipReference`s and duplicate
|
|
72
|
+
* named identifiers are skipped. Anonymous relationships are always
|
|
73
|
+
* added since each represents an independent traversal slot.
|
|
74
|
+
*/
|
|
75
|
+
addRelationship(rel) {
|
|
76
|
+
if (rel instanceof relationship_reference_1.default)
|
|
77
|
+
return;
|
|
78
|
+
const id = rel.identifier;
|
|
79
|
+
if (id !== null) {
|
|
80
|
+
if (this._seenRelationshipIdentifiers.has(id))
|
|
81
|
+
return;
|
|
82
|
+
this._seenRelationshipIdentifiers.add(id);
|
|
83
|
+
}
|
|
84
|
+
this.relationships.push(rel);
|
|
85
|
+
}
|
|
86
|
+
get isEmpty() {
|
|
87
|
+
return this.nodes.length === 0 && this.relationships.length === 0;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* Capture the currently-bound id / hop values for every registered slot.
|
|
91
|
+
* Returns `null` for ids of slots that are not currently matched (e.g.
|
|
92
|
+
* OPTIONAL MATCH misses).
|
|
93
|
+
*/
|
|
94
|
+
snapshot() {
|
|
95
|
+
var _a, _b, _c;
|
|
96
|
+
const captureProps = this._captureProperties;
|
|
97
|
+
const nodes = new Array(this.nodes.length);
|
|
98
|
+
for (let i = 0; i < this.nodes.length; i++) {
|
|
99
|
+
const node = this.nodes[i];
|
|
100
|
+
const v = node.value();
|
|
101
|
+
const binding = {
|
|
102
|
+
alias: node.identifier,
|
|
103
|
+
label: node.label,
|
|
104
|
+
id: v === null || v === undefined ? null : ((_a = v.id) !== null && _a !== void 0 ? _a : null),
|
|
105
|
+
};
|
|
106
|
+
if (captureProps && v !== null && v !== undefined) {
|
|
107
|
+
binding.properties = extractNodeProperties(v);
|
|
108
|
+
}
|
|
109
|
+
const src = v == null ? undefined : (0, virtual_sources_1.getVirtualSource)(v);
|
|
110
|
+
if (src !== undefined)
|
|
111
|
+
binding.source = src;
|
|
112
|
+
nodes[i] = binding;
|
|
113
|
+
}
|
|
114
|
+
const relationships = new Array(this.relationships.length);
|
|
115
|
+
for (let i = 0; i < this.relationships.length; i++) {
|
|
116
|
+
const rel = this.relationships[i];
|
|
117
|
+
const matches = rel.matches;
|
|
118
|
+
const hops = new Array(matches.length);
|
|
119
|
+
for (let j = 0; j < matches.length; j++) {
|
|
120
|
+
const m = matches[j];
|
|
121
|
+
const hop = {
|
|
122
|
+
left_id: m.startNode == null ? null : ((_b = m.startNode.id) !== null && _b !== void 0 ? _b : null),
|
|
123
|
+
right_id: m.endNode == null ? null : ((_c = m.endNode.id) !== null && _c !== void 0 ? _c : null),
|
|
124
|
+
type: m.type,
|
|
125
|
+
};
|
|
126
|
+
if (captureProps) {
|
|
127
|
+
hop.properties = extractRelationshipProperties(m);
|
|
128
|
+
}
|
|
129
|
+
const src = (0, virtual_sources_1.getVirtualSource)(m);
|
|
130
|
+
if (src !== undefined)
|
|
131
|
+
hop.source = src;
|
|
132
|
+
hops[j] = hop;
|
|
133
|
+
}
|
|
134
|
+
const path = hops.length === 0 ? [] : new Array(hops.length + 1);
|
|
135
|
+
if (hops.length > 0) {
|
|
136
|
+
path[0] = hops[0].left_id;
|
|
137
|
+
for (let k = 0; k < hops.length; k++) {
|
|
138
|
+
path[k + 1] = hops[k].right_id;
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
relationships[i] = {
|
|
142
|
+
alias: rel.identifier,
|
|
143
|
+
type: rel.type,
|
|
144
|
+
hops,
|
|
145
|
+
path,
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
return { nodes, relationships };
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
exports.ProvenanceSites = ProvenanceSites;
|
|
152
|
+
/**
|
|
153
|
+
* Shallow-copy a node record's user-visible property values, stripping
|
|
154
|
+
* `id` and the internal `_label` injected by `DataResolver`.
|
|
155
|
+
*/
|
|
156
|
+
function extractNodeProperties(record) {
|
|
157
|
+
const out = {};
|
|
158
|
+
for (const key of Object.keys(record)) {
|
|
159
|
+
if (key === "id" || key === "_label")
|
|
160
|
+
continue;
|
|
161
|
+
out[key] = record[key];
|
|
162
|
+
}
|
|
163
|
+
return out;
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* Shallow-copy a relationship match record's property values, stripping
|
|
167
|
+
* the structural fields (`type`, `startNode`, `endNode`, `properties`,
|
|
168
|
+
* `left_id`, `right_id`, `_type`) so what remains are the user-declared
|
|
169
|
+
* edge properties.
|
|
170
|
+
*/
|
|
171
|
+
function extractRelationshipProperties(match) {
|
|
172
|
+
// The match's nested `properties` field already holds the user-declared
|
|
173
|
+
// edge properties (set in `RelationshipMatchCollector.push`). Prefer
|
|
174
|
+
// that source when present; otherwise filter the structural fields.
|
|
175
|
+
if (match.properties && typeof match.properties === "object") {
|
|
176
|
+
return Object.assign({}, match.properties);
|
|
177
|
+
}
|
|
178
|
+
const out = {};
|
|
179
|
+
for (const key of Object.keys(match)) {
|
|
180
|
+
if (key === "type" ||
|
|
181
|
+
key === "startNode" ||
|
|
182
|
+
key === "endNode" ||
|
|
183
|
+
key === "properties" ||
|
|
184
|
+
key === "left_id" ||
|
|
185
|
+
key === "right_id" ||
|
|
186
|
+
key === "_type") {
|
|
187
|
+
continue;
|
|
188
|
+
}
|
|
189
|
+
out[key] = match[key];
|
|
190
|
+
}
|
|
191
|
+
return out;
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* Stable canonical key for deduplicating a `NodeBinding` within an aggregate
|
|
195
|
+
* group. Uses `JSON.stringify` to preserve scalar type distinctions
|
|
196
|
+
* (`1` vs `"1"`).
|
|
197
|
+
*/
|
|
198
|
+
function nodeBindingKey(b) {
|
|
199
|
+
var _a;
|
|
200
|
+
return `${(_a = b.alias) !== null && _a !== void 0 ? _a : ""}\x00${JSON.stringify(b.id)}`;
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Stable canonical key for deduplicating a `RelationshipBinding` within an
|
|
204
|
+
* aggregate group. Includes every hop so variable-length paths with the
|
|
205
|
+
* same alias but different traversals are treated as distinct.
|
|
206
|
+
*/
|
|
207
|
+
function relationshipBindingKey(b) {
|
|
208
|
+
var _a;
|
|
209
|
+
let s = `${(_a = b.alias) !== null && _a !== void 0 ? _a : ""}\x00`;
|
|
210
|
+
for (let i = 0; i < b.hops.length; i++) {
|
|
211
|
+
const h = b.hops[i];
|
|
212
|
+
s += `${JSON.stringify(h.left_id)}|${JSON.stringify(h.right_id)}|${h.type};`;
|
|
213
|
+
}
|
|
214
|
+
return s;
|
|
215
|
+
}
|
|
216
|
+
//# sourceMappingURL=provenance.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../../src/compute/provenance.ts"],"names":[],"mappings":"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"}
|
package/dist/compute/runner.d.ts
CHANGED
|
@@ -1,6 +1,110 @@
|
|
|
1
1
|
import ASTNode from "../parsing/ast_node";
|
|
2
|
-
import
|
|
3
|
-
|
|
2
|
+
import Operation from "../parsing/operations/operation";
|
|
3
|
+
import { ColumnLineage, ColumnReference, StatementInfo } from "../parsing/statement_info_crawler";
|
|
4
|
+
import { NodeBinding, RelationshipBinding, RowProvenance } from "./provenance";
|
|
5
|
+
export type { ColumnLineage, ColumnReference, StatementInfo, } from "../parsing/statement_info_crawler";
|
|
6
|
+
export type { DataSourceBinding, NodeBinding, RelationshipBinding, RelationshipHop, RowProvenance, } from "./provenance";
|
|
7
|
+
/**
|
|
8
|
+
* One slice of runtime provenance that contributed to a result cell.
|
|
9
|
+
* Pairs the column's `ColumnReference` (i.e. `alias.property`) with the
|
|
10
|
+
* matching node or relationship binding from the row provenance.
|
|
11
|
+
*/
|
|
12
|
+
export interface CellBindingTrace {
|
|
13
|
+
/** The `alias.property` reference from `ColumnLineage.references` that this binding satisfies. */
|
|
14
|
+
reference: ColumnReference;
|
|
15
|
+
/**
|
|
16
|
+
* The observed value of `reference.property` on the matched
|
|
17
|
+
* record.
|
|
18
|
+
*
|
|
19
|
+
* - For nodes: `node.id` when `reference.property === 'id'`,
|
|
20
|
+
* otherwise `node.properties?.[reference.property]`.
|
|
21
|
+
* - For relationships: built-ins (`left_id`, `right_id`, `type`)
|
|
22
|
+
* come from `hops[0]` directly; everything else comes from
|
|
23
|
+
* `hops[0].properties`. For variable-length matches over
|
|
24
|
+
* heterogeneous edges, inspect `relationship.hops` to see
|
|
25
|
+
* per-hop values.
|
|
26
|
+
*
|
|
27
|
+
* `undefined` when the binding doesn't carry that property (e.g.
|
|
28
|
+
* an OPTIONAL MATCH miss).
|
|
29
|
+
*/
|
|
30
|
+
value: any;
|
|
31
|
+
/** Present when `reference.kind === 'node'`. */
|
|
32
|
+
node?: NodeBinding;
|
|
33
|
+
/** Present when `reference.kind === 'relationship'`. */
|
|
34
|
+
relationship?: RelationshipBinding;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Combined lineage and provenance for a single result cell. Bundles
|
|
38
|
+
* the structural lineage from `metadata.info.returns[column]` with the
|
|
39
|
+
* runtime bindings from `provenance[rowIndex]` that contributed to the
|
|
40
|
+
* cell. Produced by {@link Runner.traceRow} and {@link Runner.lineage}.
|
|
41
|
+
*/
|
|
42
|
+
export interface CellTrace {
|
|
43
|
+
/** The output column name. */
|
|
44
|
+
column: string;
|
|
45
|
+
/** The cell value (`results[rowIndex][column]`). */
|
|
46
|
+
value: any;
|
|
47
|
+
/**
|
|
48
|
+
* Structural lineage for the column, copied from
|
|
49
|
+
* `metadata.info.returns[column]`. `null` when the column has no
|
|
50
|
+
* recorded structural info (e.g. unusual statement shapes that
|
|
51
|
+
* don't surface a `RETURN` to the crawler).
|
|
52
|
+
*/
|
|
53
|
+
lineage: ColumnLineage | null;
|
|
54
|
+
/**
|
|
55
|
+
* One entry per matching `(reference, binding)` pair for this row.
|
|
56
|
+
* Aggregate columns may have many entries (one per input row that
|
|
57
|
+
* fed the group); non-aggregate columns typically have one per
|
|
58
|
+
* distinct reference.
|
|
59
|
+
*
|
|
60
|
+
* Empty when the column is a literal, when the runner was not
|
|
61
|
+
* constructed with `{ provenance: true }`, or when no row binding
|
|
62
|
+
* matches the column's references.
|
|
63
|
+
*/
|
|
64
|
+
bindings: CellBindingTrace[];
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Combined structural lineage and per-row provenance for an entire
|
|
68
|
+
* Runner execution. Produced by {@link Runner.lineage}.
|
|
69
|
+
*/
|
|
70
|
+
export interface LineageReport {
|
|
71
|
+
/**
|
|
72
|
+
* Structural per-column lineage; deep copy of
|
|
73
|
+
* `metadata.info?.returns ?? {}`.
|
|
74
|
+
*/
|
|
75
|
+
columns: Record<string, ColumnLineage>;
|
|
76
|
+
/**
|
|
77
|
+
* One `{column → CellTrace}` map per result row, aligned by index
|
|
78
|
+
* with `results`. Each `CellTrace` already pairs the structural
|
|
79
|
+
* lineage with any matching row bindings.
|
|
80
|
+
*/
|
|
81
|
+
rows: Record<string, CellTrace>[];
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Optional configuration for a {@link Runner} or {@link FlowQuery}
|
|
85
|
+
* invocation.
|
|
86
|
+
*/
|
|
87
|
+
export interface RunnerOptions {
|
|
88
|
+
/**
|
|
89
|
+
* When `true`, the runner records row-level data lineage alongside the
|
|
90
|
+
* results: for each emitted row, which concrete node ids and
|
|
91
|
+
* relationship `(left_id, right_id, type)` hops were bound while the
|
|
92
|
+
* row was being projected. Access via {@link Runner.provenance}.
|
|
93
|
+
*
|
|
94
|
+
* Each {@link NodeBinding} and {@link RelationshipHop} also carries:
|
|
95
|
+
*
|
|
96
|
+
* - `properties`: a shallow copy of the matched record's user-visible
|
|
97
|
+
* property values.
|
|
98
|
+
* - `source`: when the record came from a `CREATE VIRTUAL (:X) AS
|
|
99
|
+
* { ... }` sub-query, the inner runner's `RowProvenance` row that
|
|
100
|
+
* produced it. Recursive — a virtual that matches another virtual
|
|
101
|
+
* carries nested `source` chains.
|
|
102
|
+
*
|
|
103
|
+
* Defaults to `false`; when disabled the runner has zero provenance
|
|
104
|
+
* overhead.
|
|
105
|
+
*/
|
|
106
|
+
provenance?: boolean;
|
|
107
|
+
}
|
|
4
108
|
/**
|
|
5
109
|
* Metadata about the operations performed by a Runner execution.
|
|
6
110
|
*
|
|
@@ -43,15 +147,18 @@ declare class Runner {
|
|
|
43
147
|
private _args;
|
|
44
148
|
private _isTopLevel;
|
|
45
149
|
private _metadata;
|
|
150
|
+
private _options;
|
|
151
|
+
private _provenance;
|
|
46
152
|
/**
|
|
47
153
|
* Creates a new Runner instance and parses the FlowQuery statement.
|
|
48
154
|
*
|
|
49
155
|
* @param statement - The FlowQuery statement to execute (may contain semicolon-separated statements)
|
|
50
156
|
* @param ast - An optional pre-parsed AST to use instead of parsing the statement
|
|
51
157
|
* @param args - Optional parameters to inject into $-prefixed parameter references
|
|
158
|
+
* @param options - Optional configuration (e.g. `{ provenance: true }`)
|
|
52
159
|
* @throws {Error} If the statement is null, empty, or contains syntax errors
|
|
53
160
|
*/
|
|
54
|
-
constructor(statement?: string | null, ast?: ASTNode | null, args?: Record<string, any> | null);
|
|
161
|
+
constructor(statement?: string | null, ast?: ASTNode | null, args?: Record<string, any> | null, options?: RunnerOptions);
|
|
55
162
|
private static toStatement;
|
|
56
163
|
/**
|
|
57
164
|
* Walks all statement ASTs to count CREATE/DELETE operations and to
|
|
@@ -66,6 +173,34 @@ declare class Runner {
|
|
|
66
173
|
* @throws {Error} If an error occurs during execution
|
|
67
174
|
*/
|
|
68
175
|
run(): Promise<void>;
|
|
176
|
+
/**
|
|
177
|
+
* Walks the terminal statement's operation chain and wires every
|
|
178
|
+
* MATCH-bound `Node` / `Relationship` slot to the operation that
|
|
179
|
+
* will project it. Aggregation boundaries (`AggregatedWith`,
|
|
180
|
+
* `AggregatedReturn`) absorb upstream sites into their group-level
|
|
181
|
+
* accumulation; aggregations downstream of one another chain via
|
|
182
|
+
* each `AggregatedWith` re-exposing itself as a provenance source
|
|
183
|
+
* for the next consumer.
|
|
184
|
+
*
|
|
185
|
+
* Only the last statement may produce rows; preceding statements
|
|
186
|
+
* are limited to CREATE / DELETE / REFRESH / DROP and never need
|
|
187
|
+
* row-level provenance.
|
|
188
|
+
*/
|
|
189
|
+
private enableProvenance;
|
|
190
|
+
/**
|
|
191
|
+
* Walk `first..terminal`, accumulating live MATCH sites into the
|
|
192
|
+
* "active" source list and handing it off at every aggregation
|
|
193
|
+
* boundary. Each `AggregatedWith` consumes the active list and then
|
|
194
|
+
* re-publishes itself as the single active source going forward.
|
|
195
|
+
* `Load` operations contribute per-row data-source bindings.
|
|
196
|
+
*
|
|
197
|
+
* Exposed as a public static so other components (e.g. `Let` when
|
|
198
|
+
* running a sub-query right-hand side) can wire provenance for an
|
|
199
|
+
* operation chain they drive directly, without going through the
|
|
200
|
+
* full `Runner.run` lifecycle.
|
|
201
|
+
*/
|
|
202
|
+
static wireProvenance(first: Operation, sink: RowProvenance[]): void;
|
|
203
|
+
private static collectSitesFromPattern;
|
|
69
204
|
/**
|
|
70
205
|
* Recursively walks the AST to bind ParameterReference nodes
|
|
71
206
|
* to the args provided to this Runner.
|
|
@@ -92,6 +227,64 @@ declare class Runner {
|
|
|
92
227
|
* subsequent reads.
|
|
93
228
|
*/
|
|
94
229
|
get metadata(): RunnerMetadata;
|
|
230
|
+
/**
|
|
231
|
+
* Row-level data lineage aligned by index with {@link results}.
|
|
232
|
+
*
|
|
233
|
+
* Each {@link RowProvenance} entry lists the concrete `id` values of the
|
|
234
|
+
* node slots and the `(left_id, right_id, type)` hops of the
|
|
235
|
+
* relationship slots that were bound while the corresponding result row
|
|
236
|
+
* was being projected.
|
|
237
|
+
*
|
|
238
|
+
* Returns an empty array unless the runner was constructed with
|
|
239
|
+
* `{ provenance: true }` or the query produced no rows.
|
|
240
|
+
*/
|
|
241
|
+
get provenance(): RowProvenance[];
|
|
242
|
+
/**
|
|
243
|
+
* Convenience method that bundles structural lineage with row-level
|
|
244
|
+
* provenance for a single result row. Returns one {@link CellTrace}
|
|
245
|
+
* per output column, pairing the column's
|
|
246
|
+
* {@link ColumnLineage | structural lineage} (from
|
|
247
|
+
* {@link metadata}`.info.returns`) with the node / relationship
|
|
248
|
+
* bindings (from {@link provenance}) whose alias matches one of the
|
|
249
|
+
* column's references.
|
|
250
|
+
*
|
|
251
|
+
* Equivalent to manually correlating `metadata.info.returns[col]`
|
|
252
|
+
* with `provenance[rowIndex].nodes` / `.relationships`, but with
|
|
253
|
+
* the `(alias, property) -> binding` join and the per-property
|
|
254
|
+
* value extraction done for you.
|
|
255
|
+
*
|
|
256
|
+
* @param rowIndex - Zero-based index into {@link results}.
|
|
257
|
+
* @returns A `{column -> CellTrace}` map aligned with the row.
|
|
258
|
+
* @throws {RangeError} If `rowIndex` is out of bounds for `results`.
|
|
259
|
+
*/
|
|
260
|
+
traceRow(rowIndex: number): Record<string, CellTrace>;
|
|
261
|
+
/**
|
|
262
|
+
* One-shot combined lineage and provenance report for the entire
|
|
263
|
+
* Runner execution. Returns the structural per-column lineage
|
|
264
|
+
* (deep copy of `metadata.info?.returns`) alongside one
|
|
265
|
+
* {@link traceRow} map per result row.
|
|
266
|
+
*
|
|
267
|
+
* Useful as a single object to hand to a UI, dump to a log, or
|
|
268
|
+
* snapshot for debugging. For per-cell lookups during normal flow,
|
|
269
|
+
* {@link traceRow} is cheaper.
|
|
270
|
+
*/
|
|
271
|
+
lineage(): LineageReport;
|
|
272
|
+
private static cloneColumnLineage;
|
|
273
|
+
/**
|
|
274
|
+
* Resolve `binding.property` against a captured `NodeBinding`.
|
|
275
|
+
* The built-in `id` lives at the top of the binding (it's excluded
|
|
276
|
+
* from `properties`); everything else comes from `properties`.
|
|
277
|
+
*/
|
|
278
|
+
private static readNodeProperty;
|
|
279
|
+
/**
|
|
280
|
+
* Resolve `binding.property` against a captured `RelationshipBinding`.
|
|
281
|
+
* Returns the value from `hops[0]`: the built-ins `left_id`,
|
|
282
|
+
* `right_id`, and `type` come from the hop itself, while everything
|
|
283
|
+
* else comes from `hops[0].properties`. For variable-length matches
|
|
284
|
+
* with heterogeneous hops, inspect `relationship.hops` directly to
|
|
285
|
+
* see per-hop values.
|
|
286
|
+
*/
|
|
287
|
+
private static readRelationshipProperty;
|
|
95
288
|
}
|
|
96
289
|
export default Runner;
|
|
97
290
|
//# sourceMappingURL=runner.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/compute/runner.ts"],"names":[],"mappings":"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"}
|