Store immutable "facts" in level and query them with datalog.
A fact is something that happened.
E- Entity - an id that represents an entity i.e.
A- Attribute - the attribute the fact is about i.e.
V- Value - the attribute value i.e.
T- Transaction - when this fact became true
O- Assertion/Retraction - whether the fact was asserted or retracted
The power of facts
Using a fact based information model inherently provide these 3 benefits.
1 - Flexible data model
When you write data you don't need to think much about how it will be queried later. You simply assert attributes about an entity. Facts are not tightly coupled with structure.
2 - Built in, queryable history and auditing
Most databases only remember the last thing that was true. For example:
- April 1 -user10 : Set email to "old@email"- April 6 -user10 : Set email to "new@email"- April 18 -You : What is user10's email address?aDumbDB: "new@email"You : What was user10's email on April 3?aDumbDB: "new@email"
But what you really want is this:
You : What is user10's email address?FactBase: "new@email", on April 6 it was set by user10You : What was user10's email on April 3?FactBase: "old@email", on April 1 it was set by user10, but on April 6 it was changed to "new@email" by user10
3 - Easy to query with performant joins
Fact base joins are implicit, it simply matches binding variables and unions results. The database is fully indexed for you so you don't need to worry about primary keys or indexes.
For example in SQL:
SELECTc.id,c.textFROMusers uJOIN comment c ON c.userId = u.idWHEREu.email = 'my@email'
The fact datalog equivalent:
'?uid' 'user_email' 'my@email''?cid' 'comment_userId' '?uid''?cid' 'comment_text' '?text'// implicitly joined on ?uid and ?cid
var Transactor =var db =// define a schema for attributes// like datomic schema is stored and versioned inside the databasevar schema =user_name: type: 'String'user_email: type: 'String'comment_userId: type: 'EntityID'comment_text: type: 'String'// ...var tr =// like levelup, every asynchronous function either takes a callback or returns a promise// i.e. a callbacktr// or return a Promisevar fb = await tr
Checkout example/index.js for a more complete example.
tr = Transactor(db, initSchema)
Initialize the fact-base and return a transactor (
tr for short)
dbis any thing that exposes a levelup api.
initSchemathe current expected schema for the transactor to use. As part of starting up the transactor it will sync up the schema to match what you pass it.
tr.snap() -> fb
Asynchronously get the current snapshot of the database.
tr.asOf(txn) -> fb
Asynchronously get a given
txn version of the database.
tr.transact(entities) -> fb
Assert facts and get the resulting new version of the database.
// orfb = await
fb.q(tuples, binding, select) -> results
The main entry point for performing datalog queries. Anything that starts with
'?' is a binding variable.
fb// orresults = await fb
You may also pass filter functions as the values in a binding map. Bound functions should return a boolean and filter out facts that evalutate falsy.
For more examples see
NOTE: To help prevent injection attacks, use bindings to pass in untrusted data so it's properly escaped.
fb.get($e) -> entity
A sugar function that simply gets all attributes an entity.
fb// oruser = await fb