From 6cb42f995354eae36cf57bbf5d15f57f9c94cc7e Mon Sep 17 00:00:00 2001
From: Philippe Pittoli <karchnu@karchnu.fr>
Date: Mon, 21 Apr 2025 03:08:19 +0200
Subject: [PATCH] Last annex: add a few details about the API.

---
 paper/paper.ms | 48 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/paper/paper.ms b/paper/paper.ms
index 76a80c2..7d4db85 100644
--- a/paper/paper.ms
+++ b/paper/paper.ms
@@ -2001,7 +2001,23 @@ cars_by_keywords = cars.new_tags          "keywords", &.keywords
 cars_by_keywords = cars.new_RAM_tags      "keywords", &.keywords
 .SOURCE
 .QE
-.
+
+For any trigger, in case some entries do not have the indexed value, the user-provided function has to return a
+.dq NoIndex
+value.
+.QP
+.SOURCE Ruby ps=9 vs=10
+# In case some values do not have a color or shouldn't be indexed for
+# some reason. Works the same for basic indexes and tags.
+cars_by_color = cars.new_partition  "color", do |car|
+		if color = car.color
+			color
+		else
+			DODB.no_index
+		end
+	end
+.SOURCE
+.QE
 .
 .SS Data retrieval, update and deletion with an attribute (index, partition, tags)
 .
@@ -2042,6 +2058,8 @@ Partitions and tags can take a block of code to narrow the selection.
 .SOURCE Ruby ps=9 vs=10
 cars_by_name.delete "Corvet"    # Deletes the car named "Corvet".
 cars_by_color.delete "red"      # Deletes all red cars.
+cars_by_color.delete? "yellow"  # Deletes yellow cars, if any (no MissingEntry
+                                # exception).
 
 # Deletes cars that are both slow and expensive.
 cars_by_keywords.delete ["slow", "expensive"]
@@ -2063,9 +2081,11 @@ end
 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
+.KS
 .SOURCE Ruby ps=9 vs=10
 fast_elegant_cars = cars_by_keywords.get ["fast", "elegant"]
 .SOURCE
+.KE
 Used with a list of keys, the
 .FUNCTION_CALL get
 function returns an empty list in case the search failed.
@@ -2073,3 +2093,29 @@ function returns an empty list in case the search failed.
 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
+.
+.SSS reindex
+The database can regenerate its indexes at any time by using the
+.I reindex_everything!
+function which removes all indexes (including the filesystem representation) then sets off all the triggers to index the values again.
+.QP
+.SOURCE Ruby ps=9 vs=10
+cars.reindex_everything!
+.SOURCE
+Reindexing can be used after restoring a database backup which didn't include the filesystem representation.
+
+Moreover, values could be re-indexed once a new trigger has been introduced.
+For example, the database is created and some values are added, but the admin wants a new index and all previously added values must be indexed (as new values) to keep the index consistent.
+.QE
+.
+.SS Unsafe operations
+By default, adding or removing a value in the database is thread-safe (thanks to a file-based locking mechanism).
+In case there is no need for thread-safe operations:
+.
+.QP
+.SOURCE Ruby ps=9 vs=10
+cars.unsafe_add new_car
+cars.unsafe_delete key
+.SOURCE
+Unsafe operations on the database.
+.QE