diff --git a/graphs/graphs.ms b/graphs/graphs.ms index 28a98cd..13d3fa5 100644 --- a/graphs/graphs.ms +++ b/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.