HiLo algorithm
The HiLo algorithm is an efficient solution used by a session to generate numeric parts of identifiers. In other words it is
responsible for providing numeric values that are combined with collection names to create keys like orders/10
, products/93
etc.
The client is able to determine to what type of the collection does an entity belong. In order to differ documents, it also needs to add a unique number at the end of the document's key.
To ensure that multiple clients can generate the keys simultaneously, they need some mechanism to avoid duplicates. It is ensured with Replication/HiLo/collection
documents, stored
in a database, which are modified by the clients. These documents have a very simple construction:
{
"Max": 32
}
The Max
property means the maximum possible number that has been used by any client to create the key for a given collection. It is used as follows:
- The client gets the HiLo document and reads
Max
value. - Then it adds a number (called capacity) to
Max
. - It updates the document by the new
Max
value and puts it into the database. - If someone else modified this document concurrently, the client gets
ConcurrencyException
and needs to repeat the process.
This way the client is able to generate a range of numbers it can use to generate identifiers.
Replication scenario
The usage of a replication doesn't influence the algorithm of a document ID generation. However in a Master/Master replication scenario it might be useful
to add a server specific prefix to generated document identifiers. This would help to protect against conflicts of the document IDs between the replicating servers.
In order to set up the server's prefix, you have to put Raven/ServerPrefixForHilo
document:
store.DatabaseCommands.Put("Raven/ServerPrefixForHilo", null,
new RavenJObject
{
{
"ServerPrefix", "NorthServer/"
}
},
new RavenJObject());
The ServerPrefix value will be fetch in the same request as the current HiLo document and will become a part of a generated document identifier as well.
For example, storing the first Order
object will make orders/NorthServer/1
its key.