I have a wordy post on my blog that talks a little bit about why this is and how it was designed. But it's very high-level and you shouldn't read that. This is terse and to-the-point; so read this instead.
types has a few things used to model the database and our "datoms", like
types::Value. These are used by & designed for a
sql just has a bunch of SQL query string building stuff.
The point of the library is to interact with a SQLite-backed database using entity-attribute-value "datoms" and pattern matching.
If you didn't read the blog post I linked above (I don't blame you), here's a tldr.
Consider a database that looks like ...
100 :animal/name "Cat" 100 :pet/name "Garfield" 101 :animal/name "Dog" 101 :pet/name "Odie" 102 :person/name "John Arbuckle" 100 :pet/human 102 101 :pet/human 102
And consider this pattern ...
?_ :pet/name ?_
If we were to match datoms using this pattern, we'd be asking for datoms with: any entity, for the :pet/name attribute, and any value. And we would get the following two datoms.
100 :pet/name "Garfield" 101 :pet/name "Odie"
Those are the datoms that exist that match that pattern.
Now consider two patterns together ...
?a :pet/name ?_ ?a :animal/name "Cat"
The first pattern matches the set of two datoms from earlier. The second matches just:
100 :animal/name "Cat"
But we are not interested in every combination of datoms matched by both patterns. So we related the patterns by constraining the entity to the same variable, ?a. This means that we only match the combinations of datoms between either set when they have the same entity. So we end up with one result with two datoms.
100 :pet/name "Garfield" 100 :animal/name "Cat"
It's like if we were to say:
Match every datom having the attribute :pet/name with any value and for some any entity named ?a, match also datoms on the same entity ?a having the attribute :animal/name with the value "Cat".
Another one might be:
?p :person/name ?person ?a :pet/human ?p ?a :pet/name ?pet
Here, the variables ?human and ?pet don't relate datoms together, but they're there so we can refer to them when we want to get information out.
These patterns are saying:
Given each entity ?a having the :pet/name ?pet and each entity ?p having the :person/name ?person, match only combinations of these where there exists some datom ?a :pet/human ?p. That is, where ?a's human is ?p.
The point of this library/program is to allow us to use the above expression to pattern match on our database and read values by querying variables; like ?person and ?pet to get the two results:
"John Arbuckle" "Garfield" "John Arbuckle" "Odie"
Check out the projection module for more fun documentation.
So if you read the essay over in lib.rs we saw that sequence of patterns could be used to gather sets of datoms and relate them to each other.
Wraps a rusqlite::Transaction to provide this crate's features.