refactor(rstream-query): rename types, update readme

- rename Fact => Triple, FactIds => TripleIds - rename FactGraph => TripleStore - add TripleStore.addTriples() - update TripleStore ctor
thi-ng · Apr 24, 2018 · b121c47 · b121c47
1 parent 97a6e94
commit b121c47
Show file tree

Hide file tree

Showing 9 changed files with 646 additions and 99 deletions.
diff --git a/assets/rs-query1.dot b/assets/rs-query1.dot
@@ -0,0 +1,69 @@
+digraph g {
+rankdir=LR;
+node[fontname=Inconsolata,fontsize=11,style=filled,fontcolor=white];
+edge[fontname=Inconsolata,fontsize=11];
+s0[label="S\n(Stream)", color=blue];
+s1[label="s", color=black];
+s2[label="in-s", color=black];
+s3[label="<noid>", color=gray];
+s4[label="london-raw\n(StreamSync)", color=red];
+s5[label="xform-2", color=black];
+s6[label="london", color=black];
+s7[label="sub-3", color=black];
+s8[label="<noid>", color=gray];
+s9[label="P\n(Stream)", color=blue];
+s10[label="p", color=black];
+s11[label="in-p", color=black];
+s12[label="<noid>", color=gray];
+s13[label="countries-raw\n(StreamSync)", color=red];
+s14[label="xform-0", color=black];
+s15[label="countries", color=black];
+s16[label="sub-1", color=black];
+s17[label="<noid>", color=gray];
+s18[label="O\n(Stream)", color=blue];
+s19[label="o", color=black];
+s20[label="in-o", color=black];
+s21[label="<noid>", color=gray];
+s22[label="ALL\n(Stream)", color=blue];
+s23[label="s", color=black];
+s24[label="in-s", color=black];
+s25[label="<noid>", color=gray];
+s26[label="p", color=black];
+s27[label="in-p", color=black];
+s28[label="<noid>", color=gray];
+s29[label="o", color=black];
+s30[label="in-o", color=black];
+s31[label="<noid>", color=gray];
+s7 -> s8;
+s6 -> s7;
+s5 -> s6[label="xform"];
+s4 -> s5[label="xform"];
+s3 -> s4[label="xform"];
+s2 -> s3;
+s1 -> s2[label="xform"];
+s0 -> s1[label="xform"];
+s16 -> s17;
+s15 -> s16;
+s14 -> s15[label="xform"];
+s13 -> s14[label="xform"];
+s12 -> s13[label="xform"];
+s11 -> s12;
+s10 -> s11[label="xform"];
+s9 -> s10[label="xform"];
+s21 -> s13[label="xform"];
+s20 -> s21;
+s19 -> s20[label="xform"];
+s18 -> s19[label="xform"];
+s25 -> s13[label="xform"];
+s24 -> s25;
+s23 -> s24[label="xform"];
+s28 -> s4[label="xform"];
+s27 -> s28;
+s26 -> s27[label="xform"];
+s31 -> s4[label="xform"];
+s30 -> s31;
+s29 -> s30[label="xform"];
+s22 -> s23;
+s22 -> s26;
+s22 -> s29;
+}
diff --git a/assets/rs-query1.svg b/assets/rs-query1.svg
diff --git a/packages/rstream-query/README.md b/packages/rstream-query/README.md
@@ -9,21 +9,33 @@ This project is part of the
 
 @thi.ng/rstream based [triple
 store](https://en.wikipedia.org/wiki/Triplestore) & reactive query
-engine with high re-use ratio of sub-query results. Inserted
-facts/triples are broadcast to multiple indexing streams and query
+engine with high re-use ratio of sub-query results. Inserted triples /
+facts are broadcast to multiple indexing streams and any query
 subscriptions attached to them. This enables push-based, auto-updating
-query results, which are only changing if upstream transformations &
-filters have been triggered.
+query results, which are changing each time upstream transformations &
+filters have been triggered (due to updates to the set of triples /
+facts).
 
-Unlike with traditional RDF triple stores, any JS data types can be used
-as subject, predicate or object (though support for such must be
-explicitly enabled).
+Triples are 3-tuples of `[subject, predicate, object]`. Unlike with
+traditional
+[RDF](https://en.wikipedia.org/wiki/Resource_Description_Framework)
+triple stores, any JS data types can be used as subject, predicate or
+object (though support for such must be explicitly enabled & this
+feature is currently WIP).
+
+### Current features
+
+- Entirely based on stream abstractions provided by @thi.ng/rstream
+- All data transformations done using @thi.ng/tranducers
+- Dynamic dataflow graph construction via high-level methods
+- Extensive re-use of existing sub-query results (via subscriptions)
+- Auto-updating query results
 
 ### Status
 
-This project is currently in pre-ALPHA and intended as a continuation of
-the Clojure based [thi.ng/fabric](http://thi.ng/fabric) project, this
-time built on the streaming primitives provided by
+This project is currently still in early development and intended as a
+continuation of the Clojure based [thi.ng/fabric](http://thi.ng/fabric),
+this time built on the streaming primitives provided by
 [@thi.ng/rstream](https://github.com/thi-ng/umbrella/tree/master/packages/rstream).
 
 ## Installation
@@ -35,10 +47,47 @@ yarn add @thi.ng/rstream-query
 ## Usage examples
 
 ```typescript
-import * as rstream-query from "@thi.ng/rstream-query";
+import { TripleStore } from "@thi.ng/rstream-query";
+
+store = new TripleStore();
+store.addTriples([
+    ["london", "type", "city"],
+    ["london", "part-of", "uk"],
+    ["portland", "type", "city"],
+    ["portland", "part-of", "oregon"],
+    ["portland", "part-of", "usa"],
+    ["oregon", "type", "state"],
+    ["usa", "type", "country"],
+    ["uk", "type", "country"],
+]);
+
+// find all subjects with type = country
+store.addParamQuery("countries", ["?country", "type", "country"]).subscribe(trace("country results:"));
+
+// find all relations for subject "london"
+store.addParamQuery("london", ["london", "?p", "?o"]).subscribe(trace("london results:"));
+
+// country results: [ { country: 'usa' }, { country: 'uk' } ]
+// london results: [ { p: 'type', o: 'city' }, { p: 'part-of', o: 'uk' } ]
+```
 
+After setting up the above 2 queries, the dataflow topology then looks as follows:
 
-```
+![graphviz output](../../assets/rs-query1.svg)
+
+The blue nodes are `TripleStore`-internal index stream sources, which
+emit changes when new triples are added. The red nodes are basic pattern
+queries, responsible for joining the individual (S)ubject, (P)redicate
+and (O)bject sub-queries. The results of these are then further
+transformed to bind result values to query variables, as well as the
+final subscriptions to output them to the console (using `trace`, see
+above).
+
+Btw. The diagram has been generated using
+[@thi.ng/rstream-dot](https://github.com/thi-ng/umbrella/tree/master/packages/rstream)
+and can be recreated by calling `store.toDot()` (for the above example)
+
+(Many) more features forthcoming...
 
 ## Authors
 

diff --git a/packages/rstream-query/package.json b/packages/rstream-query/package.json
@@ -1,7 +1,7 @@
 {
     "name": "@thi.ng/rstream-query",
     "version": "0.0.1",
-    "description": "TODO",
+    "description": "@thi.ng/rstream based triple store & reactive query engine",
     "main": "./index.js",
     "typings": "./index.d.ts",
     "repository": "https://github.com/thi-ng/umbrella",

diff --git a/packages/rstream-query/src/api.ts b/packages/rstream-query/src/api.ts
@@ -1,8 +1,8 @@
 export type Pattern = [any, any, any];
 
-export type Fact = Pattern;
+export type Triple = Pattern;
 
-export type FactIds = Set<number>
+export type TripleIds = Set<number>
 
 export const CHOICES = Symbol("CHOICES");
 

diff --git a/packages/rstream-query/src/index.ts b/packages/rstream-query/src/index.ts
@@ -1,4 +1,4 @@
 export * from "./api";
-export * from "./graph";
 export * from "./pattern";
 export * from "./qvar";
+export * from "./store";
diff --git a/packages/rstream-query/src/pattern.ts b/packages/rstream-query/src/pattern.ts
@@ -1,6 +1,6 @@
 import { repeatedly } from "@thi.ng/transducers/iter/repeatedly";
 
-import { Fact, Pattern } from "./api";
+import { Triple, Pattern } from "./api";
 import { isQVar, autoQVar, qvarName } from "./qvar";
 
 export const patternVarCount = (p: Pattern) => {
@@ -67,18 +67,18 @@ export const qvarResolver = (vs: boolean, vp: boolean, vo: boolean, s, p, o) =>
         default:
             return;
         case 1:
-            return (f: Fact) => ({ [oo]: f[2] });
+            return (f: Triple) => ({ [oo]: f[2] });
         case 2:
-            return (f: Fact) => ({ [pp]: f[1] });
+            return (f: Triple) => ({ [pp]: f[1] });
         case 3:
-            return (f: Fact) => ({ [pp]: f[1], [oo]: f[2] });
+            return (f: Triple) => ({ [pp]: f[1], [oo]: f[2] });
         case 4:
-            return (f: Fact) => ({ [ss]: f[0] });
+            return (f: Triple) => ({ [ss]: f[0] });
         case 5:
-            return (f: Fact) => ({ [ss]: f[0], [oo]: f[2] });
+            return (f: Triple) => ({ [ss]: f[0], [oo]: f[2] });
         case 6:
-            return (f: Fact) => ({ [ss]: f[0], [pp]: f[1] });
+            return (f: Triple) => ({ [ss]: f[0], [pp]: f[1] });
         case 7:
-            return (f: Fact) => ({ [ss]: f[0], [pp]: f[1], [oo]: f[2] });
+            return (f: Triple) => ({ [ss]: f[0], [pp]: f[1], [oo]: f[2] });
     }
 };