Baguette/dodb.cr
3
0
Fork 1
Code Issues Pull Requests Releases Wiki Activity

API documentation.

Browse Source
This commit is contained in:
Philippe PITTOLI 2024-05-17 14:08:32 +02:00
parent 789b8163e6
commit 700f86a7f5
1 changed files with 157 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

181
graphs/graphs.ms
View File

@ -15,12 +15,21 @@
.KE .KE
.QE .QE
.. ..
. .de FUNCTION_CALL
.de COMMAND
.I \\$* .I \\$*
.. ..
.
.de COMMAND
.I "\\$*"
..
.de DIRECTORY .de DIRECTORY
.I \\$* .I "\\$*"
..
.de PRIMARY_KEY
.I \\$1 \\$2 \\$3
..
.de FOREIGN_KEY
.I \\$1 \\$2 \\$3
.. ..
. .
. \" The document starts here. . \" The document starts here.
@ -46,12 +55,6 @@ Anything else is
Universities all around the world teach about Structured Query Language (SQL) and relational databases. Universities all around the world teach about Structured Query Language (SQL) and relational databases.
. .
.de PRIMARY_KEY
.I \\$1 \\$2 \\$3
..
.de FOREIGN_KEY
.I \\$1 \\$2 \\$3
..
.UL "Relational databases" .UL "Relational databases"
are built around the idea to put data into are built around the idea to put data into
@ -226,9 +229,6 @@ The file "0000000000" contains the following:
The car is serialized as expected in the file The car is serialized as expected in the file
.I 0000000000 . .I 0000000000 .
.QE .QE
.de FUNCTION_CALL
.I \\$*
..
. .
. .
Next step, to retrieve, to modify or to delete a value, its key will be required. Next step, to retrieve, to modify or to delete a value, its key will be required.
@ -490,19 +490,18 @@ database = DODB::RAMOnlyDataBase(Car).new "path/to/db-cars"
Yes, the path still is required which may be seen as a quirk but the rationale\*[*] is sound. Yes, the path still is required which may be seen as a quirk but the rationale\*[*] is sound.
.QE .QE
.FOOTNOTE1 .FOOTNOTE1
A path is still required despite the databse being only in memory for two reasons. A path is still required despite the database being only in memory because indexes can still be instanciated for the database, and those indexes will require this directory.
First, indexes can still be instanciated for the database, and those indexes can provide a file-system representation of the data. Also, I worked enough already, leave me alone.
Second, I worked enough already, leave me alone.
.FOOTNOTE2 .FOOTNOTE2
.SS RAM-only indexes .SS RAM-only indexes
All indexes have their RAM-only counterpart. Indexes have their RAM-only version.
.QP .QP
.SOURCE Ruby ps=10 .SOURCE Ruby ps=10
# RAM-only basic indexes. # RAM-only basic indexes.
cars_by_name = cars.new_RAM_index "name", &.name cars_by_name = cars.new_RAM_index "name", &.name
# RAM-only partitions. # RAM-only partitions.
cars_by_colors = cars.new_RAM_partition "color", &.color cars_by_color = cars.new_RAM_partition "color", &.color
# RAM-only tags. # RAM-only tags.
cars_by_keywords = cars.new_RAM_tags "keywords", &.keywords cars_by_keywords = cars.new_RAM_tags "keywords", &.keywords
@ -543,7 +542,7 @@ But for highly memory-constrained environments, the cache can be removed.
cars_by_name = cars.new_uncached_index "name", &.name cars_by_name = cars.new_uncached_index "name", &.name
# Uncached partitions. # Uncached partitions.
cars_by_colors = cars.new_uncached_partition "color", &.color cars_by_color = cars.new_uncached_partition "color", &.color
# Uncached tags. # Uncached tags.
cars_by_keywords = cars.new_uncached_tags "keywords", &.keywords cars_by_keywords = cars.new_uncached_tags "keywords", &.keywords
@ -556,13 +555,147 @@ is exactly the same as the others.
. .
. .
.SECTION Recap of the DODB API .SECTION Recap of the DODB API
.TBD This section provides a quick shorthand manual for the most important parts of the DODB API.
.SS Database creation For an exhaustive API documentation, please generate the development documentation for the library.
.SS Database update and deletion with the key The command
.SS Indexes creation .COMMAND "make doc"
.SS Database update and deletion with an index generates the documentation, then the
.SSS Tags: specific functions .COMMAND "make serve-doc"
command enables to browse the full documentation with a web browser.
. .
.SS Database creation
.QP
.SOURCE Ruby ps=10
# Uncached, cached and RAM-only database creation.
database = DODB::DataBase(Car).new "path/to/db-cars"
database = DODB::CachedDataBase(Car).new "path/to/db-cars"
database = DODB::RAMOnlyDataBase(Car).new "path/to/db-cars"
.SOURCE
.QE
.
.SS Browsing the database
.QP
.SOURCE Ruby ps=10
# List all the values in the database
database.each do |value|
# ...
end
.SOURCE
.QE
.QP
.SOURCE Ruby ps=10
# List all the values in the database with their key
database.each_with_index do |value, key|
# ...
end
.SOURCE
.QE
.
.SS Database search, update and deletion with the key (integer associated to the value)
.KS
.QP
.SOURCE Ruby ps=10
value = database[key] # May throw a MissingEntry exception
value = database[key]? # Return nil if the value doesn't exist
database[key] = value
database.delete key
.SOURCE
Side note for the
.I []
function: in case the value isn't in the database, the function throws an exception named
.I DODB::MissingEntry .
To avoid this exception and get a
.I nil
value instead, use the
.I []?
function.
.QE
.KE
.
.
.SS Indexes creation
.QP
.SOURCE Ruby ps=10
# Uncached, cached and RAM-only basic indexes.
cars_by_name = cars.new_uncached_index "name", &.name
cars_by_name = cars.new_index "name", &.name
cars_by_name = cars.new_RAM_index "name", &.name
# Uncached, cached and RAM-only partitions.
cars_by_color = cars.new_uncached_partition "color", &.color
cars_by_color = cars.new_partition "color", &.color
cars_by_color = cars.new_RAM_partition "color", &.color
# Uncached, cached and RAM-only tags.
cars_by_keywords = cars.new_uncached_tags "keywords", &.keywords
cars_by_keywords = cars.new_tags "keywords", &.keywords
cars_by_keywords = cars.new_RAM_tags "keywords", &.keywords
.SOURCE
.QE
.
.
.SS Database retrieval, update and deletion with an index
.QP
.SOURCE Ruby ps=10
# Get a value from an index.
car = cars_by_name.get "Corvet" # May throw a MissingEntry exception
car = cars_by_name.get? "Corvet" # Return nil if the value doesn't exist
.SOURCE
Works the same for partitions and tags, the API is consistent.
.QE
.QP
.SOURCE Ruby ps=10
# Update a value.
car = cars_by_name.update updated_car
# In case the indexed attribute changed.
car = cars_by_name.update "Corvet", updated_car
.SOURCE
.QE
.QP
.SOURCE Ruby ps=10
# In case the value may not exist.
car = cars_by_name.update_or_create updated_car
# In case the indexed attribute has changed.
car = cars_by_name.update_or_create "Corvet", updated_car
.SOURCE
.QE
.QP
.SOURCE Ruby ps=10
cars_by_name.delete "Corvet"
# Delete all red cars.
cars_by_color.delete "red"
# Delete all cars that are both blue and slow.
cars_by_color.delete "blue", do |car|
car.keywords.includes? "slow"
end
# Same.
cars_by_keywords.delete "slow", do |car|
car.color == "blue"
end
.SOURCE
.QE
.
.
.SSS Tags: search on multiple keys
The Tag index enables to search for a value based on multiple keys.
For example, searching for all cars that are both fast and elegant can be written this way:
.QP
.SOURCE Ruby ps=10
fast_elegant_cars = cars_by_keywords.get ["fast", "elegant"]
.SOURCE
Used with a list of keys, the
.FUNCTION_CALL get
function returns an empty list in case the search failed.
.br
The implementation was designed to be simple (7 lines of code), not efficient.
However, with data and index caches, the search is expected to meet about everyone's requirements, speed-wise, given that the tags are small enough (a few thousand entries).
.QE
. .
. .
.SECTION Limits of DODB .SECTION Limits of DODB