Sharding: Anchoring Documents

To anchor a document, add its ID a suffix: the $ symbol, followed by the ID of the anchor document.
<anchored document ID> + $ + <anchor document ID>

In the example below, the document named Users/70$Users/4 is placed in the same bucket as its anchor, Users/4.

Anchored Documents

• Users cannot select a document's bucket explicitly by its number, but only by adding a suffix by which the bucket number is calculated.

• It is possible to anchor multiple documents to the same document.
  E.g., naming three documents Users/70$Users/4, Users/71$Users/4, and Users/72$Users/4 will make the database store these documents in the same bucket as Users/4.

• It is possible to anchor multiple documents to the same bucket using an arbitrary name that represents no existing document.
  E.g., Users/1$foo and Users/2$foo will share a bucket.

Example 1

Explicitly store a document with another document's name as a suffix, to keep both documents in the same bucket.
In this case, keep an invoice in the same bucket as its order.

// The invoice will be stored with the order ID as a suffix
session.Store(invoice, invoice.Id + "$" + order.Id);
session.SaveChanges();

Example 2

Define and use a naming convention for invoices.
Whenever an invoice is stored, the $ symbol and an order ID are automatically added to the invoice's ID to assure that invoices and orders are kept in the same bucket.

// Store an invoice document in the same bucket as its order document

// Register a naming convention for invoices
// When an invoice is stored, the $ symbol and an order ID are added to the invoice ID
var conventions = new DocumentConventions();
conventions.RegisterAsyncIdConvention<Invoice>(async (dbName, r) =>
{
    var id = await conventions.AsyncDocumentIdGenerator(dbName, r);
    return $"{id}${r.OrderId}";
});

// Implement the naming convention we define above
using (var store = new DocumentStore()
{
    Urls = new[] { "http://127.0.0.1:8080" },
    Database = "Products",
    Conventions = conventions
}.Initialize())
{
    using (var session = store.OpenSession())
    {
        var order = new Order
        {
        };
        session.Store(order);
        var invoice = new Invoice
        {
            OrderId = order.Id
        };
        // The invoice will be stored with the order ID as a suffix
        session.Store(invoice);
        session.SaveChanges();
    } 
}