UAV database is a tuple space database that is easy to use and easy to grasp. There is also a database server that allows to query the database from multiple processus.
We will get started by using the database directly without the database server illustrated with an music album collection kind of stuff and then will open the road to use the database server.
You can fetch the lasted version of UAV database using git:
git clone https://framagit.org/a-guile-mind/guile-wiredtiger.git
What is the tuple space? It's table with three columns.
In what follows we consider the following assoc:
(define lagale-lagale '((artist . "La Gale") (title . "La Gale") (year . 2012)))
U
The first column U
stands for unique identifier. it's a random
string assigned the first time you add an assoc to the database. A
single assoc is represented with several rows in the table but share
the same identifier.
A
A
stands for attribute name. In the above example it's title
and
year
. In this case attributes are symbols but can be any scheme
value that can be serialized with write
.
V
The last column is V
for value. It can be any scheme value that
can be serialized with write
.
If we add lagale-lagale
to the database, and the assigned unique
identifier is ABCDE
, the database will more or less look like the
following:
uid | attribute | value =======+============+=========== ABCDE | artist | "La Gale" -------+------------+----------- ABCDE | title | "La Gale" -------+------------+----------- ABCDE | year | 2012
Fire an REPL inside the wiredtiger directory using the following command:
wiredtiger $ guile -L .
And load the uav
module with:
(use-modules (uav))
To get started you need to open database:
(define connexion (uav-open* "/tmp/"))
To add a document to the database you simply format you data into an assoc and use uav-add!:
(define uid (uav-add! '((artist . "La Gale") (title . "La Gale") (year . 2012))))
There is a debug procedure that allows to have a pick at the
underlying schema. Using uav-debug
you will get something like the
following:
scheme@(guile-user)> (uav-debug) ;;; (key ("DZI3P5MU" "artist")) ;;; (value ("\"La Gale\"")) ;;; (key ("DZI3P5MU" "title")) ;;; (value ("\"La Gale\"")) ;;; (key ("DZI3P5MU" "year")) ;;; (value ("2012"))
Now you can use uav-ref*
to retrieve the document using its uid
:
scheme@(guile-user)> (uav-ref* uid) $3 = ((year . 2012) (title . "La Gale") (artist . "La Gale"))
We assigned previously the identifier of La Gale album to uid
.
We can with this information update the document with uav-update!
.
The thing to keep in mind is that this procedure updates the whole
document so you need first to retrieve the original assoc, update
the assoc and commit the new version using uav-update!
.
For instance, let's add the genre to the assoc:
scheme@(guile-user)> (uav-ref* uid) $6 = ((year . 2012) (title . "La Gale") (artist . "La Gale")) scheme@(guile-user)> (acons 'genre "Hip Hop" $3) $7 = ((genre . "Hip Hop") (year . 2012) (title . "La Gale") (artist . "La Gale")) scheme@(guile-user)> (uav-update! uid $7) scheme@(guile-user)> (uav-ref* uid) $8 = ((year . 2012) (title . "La Gale") (genre . "Hip Hop") (artist . "La Gale"))
Let's check the output of uav-debug
:
scheme@(guile-user)> (uav-debug) ;;; (key ("DZI3P5MU" "artist")) ;;; (value ("\"La Gale\"")) ;;; (key ("DZI3P5MU" "genre")) ;;; (value ("\"Hip Hop\"")) ;;; (key ("DZI3P5MU" "title")) ;;; (value ("\"La Gale\"")) ;;; (key ("DZI3P5MU" "year")) ;;; (value ("2012"))
There is a new key/value pair with a genre
attribute associated with
"Hip Hop
.
To delete a document you simply use (uav-del! uid)
procedure:
scheme@(guile-user)> (uav-del! uid) scheme@(guile-user)> (uav-debug) scheme@(guile-user)>
As you can see uav-debug
displays nothing, the database is empty!
You can retrieve document using attribute-value association. Otherwise said, you can retrieve every document that has a given attribute/value pair in its assoc.
Let re-add lagale-lagale
to the database an try to retrieve it by year:
scheme@(guile-user)> (uav-add! '((artist . "La Gale") (title . "La Gale") (year . 2012)))
Let's add another album
scheme@(guile-user)> (uav-add! '((artist . "La Gale") (title . "Salem City Rocker") (year . 2015)))
Let's add the album of another artist:
scheme@(guile-user)> (uav-add! '((artist . "Mighz") (title . "Equilibre") (year . 2015)))
Now it's funny enough to query the database! Let's try uav-index-ref
:
scheme@(guile-user)> (uav-index-ref 'year 2012) $16 = ("3UTO7NW0") scheme@(guile-user)> (uav-index-ref 'year 2015) $17 = ("WCKA2IWH" "PQVA9NBB")
That's all folks!