DODB: basic usage and basic indexes.

graphs/graphs.ms

@@ -14,6 +14,13 @@
 .QE
 ..
 .
+.de COMMAND
+.I \\$*
+..
+.de DIRECTORY
+.I \\$*
+..
+.
 . \" The document starts here.
 .
 .TITLE Document Oriented DataBase (DODB)
@@ -154,6 +161,8 @@ DODB is a hash table.
 The key of the hash is an auto-incremented number and the value is the stored data.
 The following section will explain how to use DODB for basic cases including the few added mechanisms to speed-up searches.
 Also, the file-system representation of the data will be presented since it enables easy off-application searches.
+.
+.
 .SS Before starting: the example database
 First things first, the following code is the structure used in the rest of the document to present the different aspects of DODB.
 This is a simple object
@@ -166,6 +175,8 @@ class Car
 	property keywords : Array(String)
 end
 .SOURCE
+.
+.
 .SS DODB basic usage
 Let's create a DODB database for our cars.
 .SOURCE Ruby ps=10
@@ -210,36 +221,138 @@ The file "0000000000" contains the following:
   ]
 }
 .SOURCE
+The car is serialized as expected in the file
+.I 0000000000 .
 .QE
+.de FUNCTION_CALL
+.I \\$*
+..
+.
+.
+Next step, to retrieve, to modify or to delete a value, its key will be required.
+.
+.QP
+.SOURCE Ruby ps=10
+# Get a value based on its key.
+db[key]
+
+# Update a value based on its key.
+db[key] = new_value
+
+# Delete a value based on its key.
+db.delete 0
+.SOURCE
+.QE
+.
+The function
+.FUNCTION_CALL each_with_index
+lists the entries with their keys.
+.
+.QP
+.SOURCE Ruby ps=10
+db.each_with_index do |value, key|
+	puts "#{key}: #{value}"
+end
+.SOURCE
+.QE
+Of course, browsing the entire database to find a value (or its key) is a waste of resources and isn't practical for any non-trivial database.
+That is when indexes come into play.
+.
+.
 .SS Indexes
-Database entries can be
+Entries can be
 .I indexed
 based on their attributes.
-There are currently three main ways to search a value by its attributes: basic indexes, partitions and tags.
-.SSS Basic indexes (1 to 1 relation)
+There are currently three main ways to search for a value by its attributes: basic indexes, partitions and tags.
+.
+.SSS Basic indexes (1 to 1 relations)
 Basic indexes represent one-to-one relations, such as an index in SQL.
-For example, in a database of
-.I cars ,
-each car can have a dedicted (unique) name.
+In the Car database, each car has a dedicated (unique) name.
 This
 .I name
 attribute can be used to speed-up searches.
-On the file-system, this will be translated as this:
+.QP
+.SOURCE Ruby ps=10
+# Create an index based on the "name" attribute of the cars.
+cars_by_name = cars.new_index "name", do |car|
+	car.name
+end
+.SOURCE
+Once the index has been created, every added or modified entry in the database will be indexed.
+.QE
+.
+Adding an index (basic index, partition or tag) provides an object used to manipulate the database based on this index.
+.QP
+.SOURCE Ruby ps=10
+# Retrieve the car named "Corvet".
+corvet = cars_by_name.get? "Corvet"
+
+# Modify the car named "Corvet".
+new_car = Car.new "Corvet", "green", ["eco-friendly"]
+cars_by_name.update "Corvet", new_car
+
+# In case the index hasn't changed (the name attribute in this example),
+# the update can be even simpler.
+new_car = Car.new "Corvet", "green", ["eco-friendly"]
+cars_by_name.update new_car
+
+# Delete the car named "Corvet".
+cars_by_name.delete "Corvet"
+.SOURCE
+A car can now be searched, modified or deleted based on its name.
+.QE
+.
+.
+On the file-system, indexes are represented as symbolic links.
 .TREE1
 storage
 +-- data
-|    `-- 0000000000
+|    `-- 0000000000   <- the car named "Corvet"
 `-- indexes
       `-- by_name
-          `-- Ford C-MAX -> ../../data/0000000000
+          `-- Corvet -> ../../data/0000000000
 .TREE2
-As shown, the file "Ford C-MAX" is a symbolic link to a data file.
+.QP
+As shown, the file "Corvet" is a symbolic link to a data file.
 The name of the symlink file has been extracted from the value itself, enabling to list all the cars and their names with a simple
-.UL ls
+.COMMAND ls
 in the
-.I storage/indexes/by_name/
+.DIRECTORY storage/indexes/by_name/
 directory.
-.TBD
+.QE
+.
+The basic indexes as shown in this section already give a taste of what is possible to do with DODB.
+The following indexes will cover some other usual cases.
+.
+.SSS Partitions (1 to n relations)
+An attribute can have a value that is shared by other entries in the database, such as the
+.I color
+attribute in our cars.
+.
+.TREE1
+db-cars
++-- data
+|    +-- 0000000000   <- this car is blue
+|    `-- 0000000001   <- this car is red
+|   ...
+`-- partitions
+      `-- by_color
+        +-- blue
+             `-- 0000000000 -> 0000000000
+        `-- red
+             `-- 0000000001 -> 0000000001
+.TREE2
+.QP
+Listing all the blue cars is simple as a
+.COMMAND ls
+in the
+.DIRECTORY db-cars/partitions/by_color/blue
+directory!
+.QE
+.
+.SSS Tags (n to n relations)
+Tags are basically partitions but the attribute can have multiple values.
+.
 .SECTION A few more options
 .TBD
 .SECTION Limits of DODB
@@ -292,6 +405,7 @@ class Car
 end
 .SOURCE
 .
+.
 .SS Basic indexes (1 to 1 relations)
 .LP
 An index enables to match a single value based on a small string.