Data Modelling & Querying with Relatude.DB#

A practical manual

Relatude.DB is an open-source, C#-native object-oriented graph database with integrated full-text (BM25) search, vector/semantic search, file storage, faceting and a built-in admin UI. It runs in-process or server-hosted, and targets .NET 8+.

This manual covers the part of the engine you touch every day: how to shape your data, and how to get it back out. It uses one running example domain — a venue-and-events platform — so every concept builds on the last.

Version note. Relatude.DB is pre-1.0 and the public API still moves. Everything in this manual is taken from the source at github.com/Relatude/Relatude.DB under src/Relatude.DB.NodeStore/ and src/Relatude.DB.Common/. When something here disagrees with your build, the source wins.

Part I — Data modelling#

1. The mental model#

Everything in Relatude.DB is a node. A node has:

There is no separate "schema language". Your C# types are the schema. Point the engine at a namespace and it builds the datamodel from your interfaces and classes.

Interfaces are the model#

A node type can be an interface, a class, a record or a struct — the engine supports all four. No attribute is needed to opt in: every type in a namespace you point the engine at becomes a node type unless it is marked [Exclude]. [Node] only tunes one (see stable type ids below), which is why almost no type in this manual carries it. Interfaces are the recommended default, and the rest of this manual models almost everything with interfaces alone.

The headline: you do not need a class at all. An interface on its own is a complete node type. store.Create<IVenue>() hands you a generated proxy that implements it, tracks your changes and lazily loads relations. No concrete class is ever written, and none is needed.

The reason to prefer interfaces goes beyond saving a file: C# allows a type to implement many interfaces but inherit only one class. Because Relatude.DB treats every interface a node type implements as a parent node type, interface-based modelling gives you real multiple inheritance in the datamodel — shared, queryable facets that cut across your hierarchy. Classes cannot do this.

§2 works through it.

2. Your first node type#

The three namespaces you will import in every model file:

using Relatude.DB.Common;       // FileValue, GeoCoordinate, NodeKey
using Relatude.DB.Datamodels;   // NodeMeta, RevisionType
using Relatude.DB.Nodes;        // attributes, relation bases, Reference, References, EmbeddedMap

Here is IOrganizer — a company that runs events. This interface is the entire node type. There is no class, and none is needed:

namespace VenueApp.Models;

public interface IOrganizer {
    Guid Id { get; set; }

    [DisplayNameProperty]
    [StringProperty(Indexed = true, MaxLength = 200, IndexedByWords = true)]
    string Name { get; set; }

    [StringProperty(StringType = StringValueType.Email, UniqueValues = true)]
    string ContactEmail { get; set; }

    [StringProperty(Indexed = true, UniqueValues = true, RegularExpression = @"^[a-z0-9-]+$")]
    string Slug { get; set; }

    [CreatedUtcProperty]
    DateTime CreatedUtc { get; set; }

    NodeMeta Meta { get; }          // read-only on the interface
}

That is it. You now have a full node type:

var org = db.Create<IOrganizer>();      // a generated proxy implementing IOrganizer
org.Name = "Nordic Live AS";
org.ContactEmail = "hello@nordiclive.no";
db.Insert(org);

var again = db.Get<IOrganizer>(org.Id);
var all   = db.Query<IOrganizer>().Where(o => o.Name.StartsWith("Nordic")).Execute();

Three rules for interface node types:

1. Meta is getter-only. So are relation, reference and embedded properties. The proxy owns their initialisation — you never assign them. Scalar properties are { get; set; }.
2. Leave Id as Guid.Empty on insert and the store assigns one, or set it yourself first.
3. Put your attributes on the interface. Property definitions live on the type that first declares them, so an attribute on a class that merely implements an interface member is ignored. The interface is the single source of truth for the property model.

Add [Exclude] to any type or property the datamodel should skip.

Why interfaces are the better default#

The practical effect: an interface model is shorter, has no initialisation boilerplate to forget, and — the big one — composes.

Multiple inheritance with interfaces#

When the engine builds a node type it records every interface the type implements as a parent node type. So interfaces are not just a declaration style; they are the inheritance mechanism. And because a C# type may implement any number of interfaces, you get modelling shapes that a single-base-class hierarchy simply cannot express.

Define small, focused facet interfaces:

// A thing that sits somewhere on the map.
public interface ILocatable {
    [GeoCoordinateProperty(Indexed = true)]
    GeoCoordinate Location { get; set; }

    [StringProperty(Indexed = true, MaxLength = 2)]
    string CountryCode { get; set; }
}

// A thing with an identity, a name and a slug.
public interface INamedNode {
    Guid Id { get; set; }
    NodeMeta Meta { get; }

    [DisplayNameProperty]
    [StringProperty(Indexed = true, IndexedByWords = true, PrefixSearch = true)]
    string Title { get; set; }

    [AddressProperty]
    [StringProperty(Indexed = true, UniqueValues = true)]
    string Slug { get; set; }
}

// A thing with a rich-text body that should be searchable.
public interface IDescribed {
    [HtmlProperty(IndexedByWords = true, IndexedBySemantic = true)]
    string Description { get; set; }
}

// A thing that can be tagged.
public interface ITagged {
    [StringArrayProperty(Indexed = true)]
    string[] Tags { get; set; }
}

…then compose them freely, mixing and matching per type:

public interface IVenue    : INamedNode, IDescribed, ILocatable, ITagged { /* venue-only    */ }
public interface IEvent    : INamedNode, IDescribed,              ITagged { /* event-only    */ }
public interface IAttendee : INamedNode,              ILocatable          { /* attendee-only */ }

Each facet's properties are declared exactly once, with their indexing and validation attached, and every implementing type inherits them. Change ILocatable.Location to Indexed = false and both venues and attendees follow. Add a fifth node type that should appear on the map and it is one interface in the declaration — no property copying, no query to update.

A class-based model cannot express this. Venue can inherit one base class, so the moment you want "locatable" and "described" and "tagged" you are copying properties between types and keeping their attributes in sync by hand.

Querying across the hierarchy#

This is where multiple inheritance pays off at runtime. Query<T>() matches T and every type descending from it, so you can query a facet interface directly and get heterogeneous results:

// Every locatable node of any type within 5 km — venues and attendees together
var nearby = db.Query<ILocatable>()
               .Where(x => x.Location.IsWithin(oslo, 5_000))
               .Execute();

foreach (var x in nearby) {
    Console.WriteLine(x switch {
        IVenue v    => $"Venue: {v.Title}",
        IAttendee a => $"Attendee: {a.Title}",
        _           => "Something else"
    });
}

// One search box over everything that has a title
var hits = db.Query<INamedNode>()
             .WhereSearch("outdoor jazz", semanticRatio: 0.5)
             .Execute();

// One tag cloud over everything taggable
var tagCloud = db.Query<ITagged>().Facets().AddValueFacet(x => x.Tags).Execute();

// …narrowed back down to specific types when you want that
var venuesOnly = db.Query<ILocatable>()
                   .WhereTypes(new[] { typeof(IVenue) }, includeDescendants: true)
                   .Where(x => x.CountryCode == "NO")
                   .Execute();

A cross-cutting search page, a global "recently changed" feed, a map view that plots anything with coordinates — each is one indexed query against a facet interface, rather than one query per concrete type merged and re-sorted in memory.

The full example model in §11 declares every property directly on each type, so that each one reads as a self-contained unit. §11.1 shows the same model refactored onto facet interfaces — that is the shape to reach for in a real project.

Two constraints to design around#

The model builder is strict about ambiguity, and both rules bite exactly where you would expect:

1. Two parent interfaces may not declare the same property name. If ILocatable and ITagged both declared CountryCode, any type implementing both fails to build. Keep facets disjoint, or hoist the shared member into a base interface that both extend.
2. Property overriding is not supported. A property is defined once, on the type that first declares it. You cannot redeclare it further down to change its attributes.

Both are checked at model-build time, not at runtime, so you find out immediately.

When you do want a class#

Classes are fully supported and there are legitimate reasons to reach for one:

• You want to new nodes up yourself — in seed data, tests, or an import job — without a store.
• You want behaviour on the type: computed members, helper methods, ToString().
• You are deserialising directly into the model type from an external feed.

You can also pair an interface with a class that implements it, which gives you the interface as the queryable contract and the class as a concrete instantiable form. When you write a class, four extra obligations apply:

public class Organizer : IOrganizer {
    public Guid Id { get; set; }

    // Attributes live on IOrganizer — repeating them here has no effect.
    public string Name { get; set; } = string.Empty;
    public string ContactEmail { get; set; } = string.Empty;
    public string Slug { get; set; } = string.Empty;
    public DateTime CreatedUtc { get; set; }

    public NodeMeta Meta { get; set; } = NodeMeta.Empty;   // read-write on the class
}

1. A parameterless constructor is mandatory. The model builder throws without one.
2. Initialise every reference-typed member. string.Empty, FileValue.Empty, NodeMeta.Empty, [] for embedded maps, new() for relation and reference properties. Interfaces need none of this.
3. Meta becomes get/set. Still never build one — use NodeMeta.Empty.
4. Attributes belong on the interface when the class implements one.

Records and structs work too — a record needs the record Foo() { … } form to satisfy the parameterless-constructor rule, and structs are supported but rarely worth it.

Optional: stable type ids#

When you do not supply an id, the engine derives one by hashing the type's full name. That is convenient, but it means renaming a type or moving it to another namespace gives it a new identity — and the engine sees a brand-new type with no data. Rename-proof your model by pinning [Node(Id = …)] once, at the start of the project. The same applies to [Relation(Id = …)].

[Node(
    Id = "6a1d9f2e-0b41-4c8a-9d7b-3f2c5e8a1b40",
    TextIndex = BoolValue.True,        // include in the BM25 index
    SemanticIndex = BoolValue.False,   // skip the vector index
    TextIndexBoost = 1.5
)]
public interface IOrganizer { /* ... */ }

BoolValue is tri-state: Default (let the engine decide), True, False. [Node] also accepts MinNoInstances / MaxNoInstances to constrain how many instances of the type may exist.

3. Scalar properties and their attributes#

You can declare a plain property with no attribute at all and the engine infers a sensible property model from the CLR type. You add an attribute when you want indexing, validation, faceting or search behaviour.

The single most important flag is Indexed. A property must be indexed to be filtered, sorted or faceted efficiently. Without it, the engine falls back to scanning.

The attribute catalogue#

All of them inherit shared options from PropertyAttribute:

public abstract class PropertyAttribute : Attribute {
    public string? Id { get; set; }              // stable property id, rename-proof
    public string? ReadAccess { get; set; }      // ACL slot
    public string? WriteAccess { get; set; }
    public bool ExcludeFromTextIndex { get; set; }
    public int TextIndexBoost { get; set; }
    public bool DisplayName { get; set; }
}

Strings#

[StringProperty] is the richest of the set:

[StringProperty(
    MinLength = 0,
    MaxLength = 4000,
    StringType = StringValueType.AnyString,  // AnyString | HTML | Url | Email | ...
    Indexed = true,                          // value index: equality, range, sort
    IndexedByWords = true,                   // BM25 full-text index
    IndexedBySemantic = true,                // vector / semantic index
    PrefixSearch = true,                     // "starts with" index
    InfixSearch = false,                     // "contains" index (expensive — opt in deliberately)
    PreloadWordIndex = false,
    MinWordLength = 3,
    MaxWordLength = 30,
    LegalValues = new[] { "draft", "published", "cancelled" },
    RegularExpression = @"^[a-z0-9-]+$",
    UniqueValues = true,
    IgnoreDuplicateEmptyValues = true,       // allow many empty values under UniqueValues
    NotFacet = false,                        // exclude from faceting even when indexed
    DefaultValue = ""
)]
public string Slug { get; set; } = string.Empty;

Use [HtmlProperty] for rich text so the HTML is stripped before word indexing:

[HtmlProperty(IndexedByWords = true, IndexedBySemantic = true)]
public string Description { get; set; } = string.Empty;

Numbers#

Numeric attributes share MinValue / MaxValue / DefaultValue / Indexed / NotFacet, plus range-faceting controls:

[IntegerProperty(MinValue = 0, MaxValue = 100000, Indexed = true)]
public int Capacity { get; set; }

[DoubleProperty(Indexed = true, FacetRangePowerBase = 2.0, FacetRangeCount = 8)]
public double AverageRating { get; set; }

FacetRangePowerBase and FacetRangeCount control how the engine auto-buckets a numeric property when you ask for a range facet.

decimal, DateTime, DateTimeOffset, TimeSpan and Guid are not legal C# attribute parameter types, so their bounds and defaults are passed as strings in a fixed format:

// decimal — invariant culture
[DecimalProperty(MinValue = "0", MaxValue = "100000", DefaultValue = "0", Indexed = true)]
public decimal Price { get; set; }

// DateTime / DateTimeOffset — round-trip ("O") format
[DateTimeProperty(MinValue = "2000-01-01T00:00:00.0000000Z", Indexed = true)]
public DateTime StartsUtc { get; set; }

// TimeSpan — constant ("c") format
[TimeSpanProperty(MaxValue = "1.00:00:00", Indexed = true)]
public TimeSpan Duration { get; set; }

// Guid — plain string form
[GuidProperty(Indexed = true, UniqueValues = true)]
public Guid ExternalRef { get; set; }

Enums#

Declare the property as your enum type. The engine stores it as an integer and auto-populates the enum metadata (FullEnumTypeName, LegalValues, LegalValueNames) so the admin UI and facets show names rather than numbers:

public enum EventStatus { Draft = 0, Published = 1, SoldOut = 2, Cancelled = 3 }

[IntegerProperty(Indexed = true)]
public EventStatus Status { get; set; }

Arrays of enums use [EnumArrayProperty], which carries the same auto-populated metadata:

[EnumArrayProperty(Indexed = true)]
public AccessibilityFeature[] Accessibility { get; set; } = [];

Validation happens on write#

LegalValues, RegularExpression, MinValue/MaxValue, MinLength/MaxLength, UniqueValues and MinNoInstances/MaxNoInstances are all enforced by the engine at write time. A violating transaction fails rather than silently storing bad data.

4. Marker properties#

Six attributes tag a property as playing a special structural role. At most one property per type per role.

[DisplayNameProperty]
[StringProperty(Indexed = true, IndexedByWords = true)]
public string Title { get; set; } = string.Empty;

[AddressProperty]
[StringProperty(Indexed = true, UniqueValues = true)]   // UniqueValues only when URLs are flat, see §18
public string Address { get; set; } = string.Empty;

[CreatedUtcProperty] public DateTime CreatedUtc { get; set; }
[ChangedUtcProperty] public DateTime ChangedUtc { get; set; }

What lives in NodeMeta#

Every node carries system metadata. Read it; never write it.

5. Geo coordinates#

GeoCoordinate (in Relatude.DB.Common) is a first-class, indexable value type for WGS84 latitude/longitude. It is a readonly struct, so it costs nothing to pass around.

using Relatude.DB.Common;

public interface IVenue {
    // ...
    [GeoCoordinateProperty(Indexed = true)]     // Indexed = true enables spatial query acceleration
    GeoCoordinate Location { get; set; }
}

Constructing and reading#

var oslo    = new GeoCoordinate(59.9139, 10.7522);
var bergen  = new GeoCoordinate(60.3913, 5.3221);

double lat  = oslo.Latitude;     // 59.9139…  (NaN when empty)
double lon  = oslo.Longitude;    // 10.7522…  (NaN when empty)

Console.WriteLine(oslo);         // "59.9139, 10.7522"

GeoCoordinate.TryParse("59.9139, 10.7522", out var parsed);   // round-trips

The empty value#

GeoCoordinate.Empty is default(GeoCoordinate) and means "no location":

var unknown = GeoCoordinate.Empty;
unknown.IsEmpty;                      // true
unknown.Latitude;                     // double.NaN
unknown.DistanceTo(oslo);             // double.PositiveInfinity
unknown.IsWithin(oslo, 100_000);      // false — never matches

Empty coordinates are excluded from spatial indexes entirely. This is exactly what you want: a venue whose location has not been entered yet should never show up in a "within 5 km" search.

Distance and radius tests#

double meters = oslo.DistanceTo(bergen);        // great-circle distance (haversine), in metres
bool   near   = oslo.IsWithin(bergen, 500_000); // true — within 500 km

IsWithin(center, meters) is the important one: the query compiler recognises it inside a query lambda and accelerates it with the spatial index. See §22 Geo queries.

How it is stored (and what that implies)#

Coordinates snap to a ~1 cm grid (31 bits per axis) on construction and are stored as a 62-bit Morton / Z-order code. Three consequences worth knowing:

• Equality, hashing and ordering coincide exactly, and every value round-trips losslessly through StorageValue / FromStorageValue.
• Sort order follows the Z-order curve, which keeps ranges spatially coherent for index scans but is meaningless as a user-facing sort. To sort by proximity, order by DistanceTo after materialising the page — do not OrderBy(v => v.Location).
• Radius searches over-scan slightly. The index cover is built from square Z-order cells; a circle is not square. The engine refines candidates with the exact haversine distance, so results are correct — but a very large radius touches more of the index than a small one.

JSON shape#

GeoCoordinate serialises as {"latitude": 59.91, "longitude": 10.75}, and Empty serialises as null so it survives a round trip. On read it also accepts lat / lon / lng aliases and a "latitude, longitude" string.

6. Files#

FileValue (in Relatude.DB.Common) is a slot into the file storage subsystem — local disk, Azure blob, and so on, configured separately in the admin UI. The property holds the reference; the bytes live in storage.

[FileProperty]
public FileValue Photo { get; set; } = FileValue.Empty;

// pin a property to a specific storage provider:
[FileProperty(FileStorageProviderId = "b1c2d3e4-...")]
public FileValue Brochure { get; set; } = FileValue.Empty;

Uploading and serving bytes is covered in §17, and the URLs they are served on in §18.

7. Embedded data#

Embedded objects are owned sub-trees. They are stored inline in the parent node, they have no independent identity in the graph, and they live and die with the parent. Reach for them when a value only makes sense in the context of its parent: opening hours on a venue, line items on an order, translations on a label.

Two flavours:

Embedded<T> — a collection keyed by the embedded object's own Guid Id#

[EmbeddedProperty(IncludeTypes = IncludeTypeOptions.ThisTypeAndDescending)]
public Embedded<PriceTier> PriceTiers { get; set; } = [];

IncludeTypeOptions controls which subtypes are allowed in the slot.

EmbeddedMap<TKey, TValue> — a collection keyed by a property of the value#

public class OpeningHours {
    public Guid Id { get; set; }
    public string DayCode { get; set; } = string.Empty;   // "mon", "tue", …
    public TimeSpan Opens { get; set; }
    public TimeSpan Closes { get; set; }
}

public interface IVenue {
    // ...
    [EmbeddedMapProperty(
        KeyProperty = nameof(OpeningHours.DayCode),
        KeyType = KeyPropertyType.NodeProperty)]      // or NodeGuidId / NodeIntegerId
    EmbeddedMap<string, OpeningHours> Hours { get; }
}

Naming a KeyProperty is enough — it takes precedence over KeyType, so the second line above is documentation rather than necessity. KeyType is what you set when there is no key property: NodeGuidId keys by the embedded value's Guid Id (which is exactly what Embedded<T> is shorthand for) and NodeIntegerId by its int id. With no attribute at all the key type is inferred from TKey: Guid → NodeGuidId, int → NodeIntegerId, anything else is an error telling you to name a KeyProperty.

The key property has to live on the closest common base of the allowed inner types, and its CLR type must equal TKey — both are checked at model-build time.

Working with an embedded map#

var venue = db.Create<IVenue>();

var monday = new OpeningHours { DayCode = "mon", Opens = new(9, 0, 0), Closes = new(23, 0, 0) };
venue.Hours.Add(monday);

db.Insert(venue);

// only *after* the parent is persisted can you read by key:
var stored = db.Get<IVenue>(venue.Id);
var mon    = stored.Hours["mon"];
int days   = stored.Hours.Count;                  // a property, not a method
bool open  = stored.Hours.Contains("mon");        // by key, not by value

foreach (var h in stored.Hours) {                 // EmbeddedMap<TKey,TValue> is IEnumerable<TValue>
    Console.WriteLine($"{h.DayCode}: {h.Opens}–{h.Closes}");
}

foreach (var (day, h) in stored.Hours.KeysAndValues()) { … }   // when you want the keys too

Gotcha. Before the parent is inserted, only Add, Clear, Count and enumeration are safe. Anything keyed — the indexer, Contains, KeysAndValues() — throws InvalidOperationException until the parent has been persisted, because the keys are evaluated by the store.

8. References — lightweight pointers#

A reference is a Guid (or an ordered Guid[]) stored directly on the node. It is a one-way pointer: cheap to store, cheap to set, and it does not create a reverse index.

public interface IEvent {
    // ...
    [ReferenceProperty(Indexed = true)]     // Indexed = true is required to filter / facet on it
    Reference<IMediaAsset> Cover { get; }

    [ReferencesProperty(Indexed = true)]
    References<IOrganizer> Sponsors { get; }
}

On a concrete class, initialise them:

public Reference<IMediaAsset>  Cover    { get; set; } = new();
public References<IOrganizer>  Sponsors { get; set; } = new();

Reading and writing a Reference<T>#

var ev = db.Get<IEvent>(eventId);

ev.Cover.IsSet();                       // is a target set at all?
ev.Cover.Id;                            // the raw Guid (Guid.Empty when unset)

if (ev.Cover.TryGet(out var asset)) {   // lazily loads the target
    Console.WriteLine(asset.FileName);
}

var img = ev.Cover.Get();               // throws when unset

ev.Cover.Set(someAssetId);              // by id
ev.Cover.Set(someAsset, db);            // by instance
ev.Cover.Clear();
db.Update(ev);                          // references are node data — persist with a normal Update

Reading and writing a References<T>#

ev.Sponsors.Ids;                        // Guid[] in stored order
ev.Sponsors.Count();
ev.Sponsors.Contains(organizerId);

ev.Sponsors.Add(organizerId);
ev.Sponsors.Add(organizerNode, db);
ev.Sponsors.Remove(organizerId);        // removes every occurrence
ev.Sponsors.Clear();
ev.Sponsors.Ids = new[] { a, b, c };    // replace wholesale, order preserved
db.Update(ev);

foreach (var sponsor in ev.Sponsors.Get()) {  // lazily loads every live target, in order
    Console.WriteLine(sponsor.Name);
}

The enumeration trap. Both Reference<T> and References<T> implement IEnumerable<T>, but foreach only yields preloaded data. If you did not .Preload(...) in the query, the foreach silently yields nothing. Use .Get() / .TryGet(out …) for lazy loading, and foreach only after a Preload. This is a deliberate design: it makes the N+1 query cost impossible to incur by accident.

Stale targets — deleted nodes, or nodes of the wrong type — are skipped by References<T>.Get() rather than throwing. With many references per value, stale entries are routine and the engine treats them as such.

9. Relations — the graph edges#

A relation is a real, bidirectional, indexed edge. Relating A to B automatically relates B back to A. Relations are what make this a graph database: they are traversable, filterable and countable without loading either side.

Relations are not foreign keys. You never store VenueId on an event. You declare a relation class, and expose one nested property class per side.

The five shapes#

// 1. Symmetric 1:1 — "spouse". Both sides are the same property.
public class PairedWith : OneOne<IVenue> {
    public class Pair : One { }
}

// 2. Directional 1:1 — "husband ↔ wife".
public class PrimaryContact : OneToOne<IOrganizer, IAttendee> {
    public class Organizer : OneFrom { }
    public class Contact   : OneTo { }
}

// 3. Directional 1:N — "parent ↔ children". The workhorse.
public class EventsAtVenue : OneToMany<IVenue, IEvent> {
    public class Venue  : One { }     // goes on IEvent   — the "one" side
    public class Events : Many { }    // goes on IVenue   — the "many" side
}

// 4. Symmetric N:N — "friends".
public class Friends : ManyMany<IAttendee> {
    public class Peers : Many { }
}

// 5. Directional N:N — "teachers ↔ students".
public class Attendance : ManyToMany<IEvent, IAttendee> {
    public class Events    : ManyFrom { }   // goes on IAttendee
    public class Attendees : ManyTo { }     // goes on IEvent
}

There is no "zero-or-one" and no asymmetric many-to-one. Model the asymmetric case as OneToMany in the appropriate direction. If your relationship genuinely does not fit — for instance because the edge itself carries data like a ticket price or a role — promote the edge to a node type with two relations hanging off it.

Using them on node types#

Each nested class becomes a property type. Give the property whatever name reads best:

public interface IVenue {
    // ...
    EventsAtVenue.Events Events { get; }          // many events at this venue
}

public interface IEvent {
    // ...
    EventsAtVenue.Venue      Venue     { get; }   // the one venue of this event
    Attendance.Attendees     Attendees { get; }   // many attendees
}

public interface IAttendee {
    // ...
    Attendance.Events Attending { get; }
    Friends.Peers     Friends   { get; }
}

On concrete classes, initialise with new():

public EventsAtVenue.Events Events { get; set; } = new();

You may omit a side you do not need. Only declare both when you want navigation in both directions.

The "one" side API#

A One / OneFrom / OneTo property is an OneProperty<T>:

var ev = db.Get<IEvent>(id);

ev.Venue.IsSet();                        // is there a related node?
ev.Venue.Count();                        // 0 or 1
var venue = ev.Venue.Get();              // throws when unset
if (ev.Venue.TryGet(out var v)) { … }    // safe probe
ev.Venue.Contains(someVenueId);

The "many" side API#

A Many / ManyFrom / ManyTo property is a ManyProperty<T>:

var venue = db.Get<IVenue>(id);

int n = venue.Events.Count();            // counted from the index — does not load the nodes
bool has = venue.Events.Contains(evId);

foreach (var e in venue.Events) { … }    // enumerates; loads lazily if not preloaded
var all = venue.Events.Get();            // IEnumerable<IEvent>

// …or keep composing as a real query, which is what you want for anything non-trivial:
var upcoming = venue.Events
                    .Query()
                    .Where(e => e.StartsUtc > DateTime.UtcNow)
                    .OrderBy(e => e.StartsUtc)
                    .Page(0, 20)
                    .Execute();

ManyProperty<T>.Query() returns a full IQueryOfNodes rooted at that relation, so everything in Part III applies to it.

Unlike Reference<T>, foreach over a Many side does load lazily when nothing was preloaded. It is still worth using .Include(...) when you are iterating many parents — see §24.

9.1 Relation lists are ordered#

A Many side is a list, not a set. Each node keeps its related items in a fixed order, and that order is stored, durable and reorderable. This is a real modelling feature: use it for hand-curated sequences — a programme running order, a menu, an image gallery, a set of related products — instead of inventing a SortIndex property and sorting on it in every query.

Four consequences to design around:

• AddRelation appends to the bottom. The most recently related item is last.
• Enumeration follows the stored order. foreach, Get() and preloaded includes all yield it, so a curated sequence survives a round trip untouched.
• Duplicates are rejected. Relating a pair that is already related throws, as does unrelating a pair that is not related. Order plus no duplicates is exactly list semantics over a set of distinct targets.
• Each side is ordered independently. In a many-to-many relation, the order of targets on a source and the order of sources on a target are two separate orderings; reordering one says nothing about the other.

A One / OneFrom / OneTo side holds at most one item, so ordering is a Many-side concept only.

The MoveRelation… family#

Six method families reorder a list. Every one exists on NodeStore — returning TransactionResult and taking flushToDisk: bool = false — and on Transaction, where it returns the Transaction so calls chain.

// offset: negative moves toward the top, positive toward the bottom
db.MoveRelation<IVenue>(venue, v => v.Events, ev, offset: -1);

db.MoveRelationToTop<IVenue>(venue, v => v.Events, headliner);
db.MoveRelationToBottom<IVenue>(venue, v => v.Events, lateAddition);

// anchor is another item already in the same list
db.MoveRelationBefore<IVenue>(venue, v => v.Events, ev, anchor: other);
db.MoveRelationAfter<IVenue>(venue, v => v.Events, ev, anchor: other);

// replace the whole order in one call
db.SetRelationOrder<IVenue>(venue, v => v.Events, orderedEvents);

Chained inside a transaction — relate and position in one commit:

var t = db.CreateTransaction();
t.AddRelation<IVenue>(venue, v => v.Events, ev)
 .MoveRelationToTop<IVenue>(venue, v => v.Events, ev)
 .Execute();

Semantics#

• Multi-item moves behave like a list UI. Pass a collection instead of a single item and the selection keeps its internal order and compacts against the ends of the list — the behaviour you want behind a multi-select drag handle.
• Positions are clamped. Moving past the top or bottom never throws.
• SetRelationOrder reorders; it does not add or remove. The ids you supply must be exactly the currently related ids.
• Never reorder by un-relating and re-relating. Beyond being two writes instead of one, a re-AddRelation lands at the bottom, and re-relating an already-related pair throws.

Overload shapes#

Each family takes a single item or an IEnumerable of items, in three addressing styles:

MoveRelationToTop<T>(T fromNode,  Expression<Func<T, object?>> expression, object item)
MoveRelationToTop<T>(Guid fromId, Expression<Func<T, object?>> expression, Guid item)
MoveRelationToTop   (Guid fromId, Guid propertyId,                         Guid item)

MoveRelation adds int offset; MoveRelationBefore / MoveRelationAfter add an anchor of the same shape as item; SetRelationOrder takes only itemsInOrder. On Transaction the same families also accept int internal ids. Prefer the expression form — readable and type-checked.

For raw relation-id access there is TransactionRelation.Move(relationId, owner, items, offset, reorderSourcesOfTarget = false), where reorderSourcesOfTarget: true reorders a target's list of sources rather than the owner's list of targets. Only meaningful for many-to-many, and rarely what you want from application code.

Relation options#

[Relation(
    Id = "9f4e2c11-77a3-4d5e-8b21-0c6f9a3e7d54",  // stable id, survives renames
    DisallowCircularReferences = true              // enforce acyclicity on self-referential relations
)]
public class VenueTree : OneToMany<IVenue, IVenue> {
    public class Parent   : One { }
    public class Children : Many { }
}

[Relation] also accepts SourceTypes / TargetTypes as full type-name strings, but the generic parameters already carry that information — you rarely need them.

Relation properties can also feed the parent's text index, which is how you make a venue findable by the names of the events held there:

[RelationProperty(
    TextIndexRelatedDisplayName = true,
    TextIndexRelatedContent = false,
    TextIndexRecursiveLevelLimit = 1,
    Facet = true                          // opt in to faceting on this relation
)]
public EventsAtVenue.Events Events { get; }

10. Choosing between relation, reference and embedded#

This is the decision you will make most often. The short version:

Decision guide

• The child has no meaning outside the parent, and you never query it independently → embedded.
• You need the same target more than once, and you never need the reverse lookup → References<T>. Note that ordering by itself is not a reason to pick this: relation lists are ordered too, and come with reorder operations that references do not have.
• You point at one thing, cheaply, and never ask "what points at me?" → Reference<T>.
• You need reverse navigation, traversal, relation filters, relation facets, a curated order you can rearrange, or referential bookkeeping → relation. When in doubt, this is the right default.

Applied to the running example:

• Venue.Hours → embedded. Opening hours are meaningless without their venue.
• Event.Cover → Reference<IMediaAsset>. One-way pointer; nobody asks "which events use this image?" from the image side.
• Event.Sponsors → References<IOrganizer>. The same organizer can appear twice at different billing tiers, and we never ask an organizer for its sponsored events from that property. Order matters here, but that alone would not decide it — a relation would give ordering too, plus reorder operations; duplicates are what rule a relation out.
• Event ↔ Venue, Event ↔ Attendee → relations. Both directions are navigated constantly, and a venue's event list is curated by hand — which the relation's stored order handles for free.

11. The complete example model#

Here is the whole running domain in one place. Everything in Part II and Part III queries this model.

using Relatude.DB.Common;
using Relatude.DB.Datamodels;
using Relatude.DB.Nodes;

namespace VenueApp.Models;

public enum EventStatus { Draft = 0, Published = 1, SoldOut = 2, Cancelled = 3 }
public enum VenueKind   { Indoor = 0, Outdoor = 1, Hybrid = 2 }

// ────────────────────────────────────────────────────────────────────────────
//  Node types
// ────────────────────────────────────────────────────────────────────────────

public interface IOrganizer {
    Guid Id { get; set; }
    NodeMeta Meta { get; }

    [DisplayNameProperty]
    [StringProperty(Indexed = true, MaxLength = 200, IndexedByWords = true)]
    string Name { get; set; }

    [StringProperty(StringType = StringValueType.Email, UniqueValues = true)]
    string ContactEmail { get; set; }

    [AddressProperty]
    [StringProperty(Indexed = true, UniqueValues = true, RegularExpression = @"^[a-z0-9-]+$")]
    string Slug { get; set; }

    [CreatedUtcProperty] DateTime CreatedUtc { get; set; }

    OrganizerEvents.Events Events { get; }
}

public interface IVenue {
    Guid Id { get; set; }
    NodeMeta Meta { get; }

    [DisplayNameProperty]
    [StringProperty(Indexed = true, IndexedByWords = true, PrefixSearch = true)]
    string Name { get; set; }

    [AddressProperty]
    [StringProperty(Indexed = true, UniqueValues = true)]
    string Slug { get; set; }

    [HtmlProperty(IndexedByWords = true, IndexedBySemantic = true)]
    string Description { get; set; }

    [GeoCoordinateProperty(Indexed = true)]
    GeoCoordinate Location { get; set; }

    [StringProperty(Indexed = true, MaxLength = 2)]
    string CountryCode { get; set; }

    [IntegerProperty(Indexed = true, MinValue = 0)]
    int Capacity { get; set; }

    [IntegerProperty(Indexed = true)]
    VenueKind Kind { get; set; }

    [BooleanProperty(Indexed = true)]
    bool IsAccessible { get; set; }

    [FileProperty]
    FileValue Photo { get; set; }

    [EmbeddedMapProperty(KeyProperty = nameof(OpeningHours.DayCode))]
    EmbeddedMap<string, OpeningHours> Hours { get; }

    VenueTree.Parent        Parent { get; }   // e.g. a hall inside a complex
    VenueTree.Children      Halls  { get; }
    EventsAtVenue.Events    Events { get; }
}

public interface IEvent {
    Guid Id { get; set; }
    NodeMeta Meta { get; }

    [DisplayNameProperty]
    [StringProperty(Indexed = true, IndexedByWords = true, IndexedBySemantic = true, PrefixSearch = true)]
    string Title { get; set; }

    [HtmlProperty(IndexedByWords = true, IndexedBySemantic = true)]
    string Description { get; set; }

    [DateTimeProperty(Indexed = true)]
    DateTime StartsUtc { get; set; }

    [TimeSpanProperty(Indexed = true, MaxValue = "1.00:00:00")]
    TimeSpan Duration { get; set; }

    [DecimalProperty(Indexed = true, MinValue = "0", DefaultValue = "0",
                     FacetRangePowerBase = 2.0, FacetRangeCount = 6)]
    decimal Price { get; set; }

    [IntegerProperty(Indexed = true)]
    EventStatus Status { get; set; }

    [StringArrayProperty(Indexed = true)]
    string[] Tags { get; set; }

    [ReferenceProperty(Indexed = true)]
    Reference<IMediaAsset> Cover { get; }

    [ReferencesProperty(Indexed = true)]
    References<IOrganizer> Sponsors { get; }

    EventsAtVenue.Venue    Venue     { get; }
    OrganizerEvents.Host   Host      { get; }
    Attendance.Attendees   Attendees { get; }
}

public interface IAttendee {
    Guid Id { get; set; }
    NodeMeta Meta { get; }

    [DisplayNameProperty]
    [StringProperty(Indexed = true, IndexedByWords = true)]
    string FullName { get; set; }

    [StringProperty(StringType = StringValueType.Email, Indexed = true, UniqueValues = true)]
    string Email { get; set; }

    [GeoCoordinateProperty(Indexed = true)]
    GeoCoordinate HomeLocation { get; set; }

    Attendance.Events Attending { get; }
    Friends.Peers     Friends   { get; }
}

public interface IMediaAsset {
    Guid Id { get; set; }
    NodeMeta Meta { get; }

    [DisplayNameProperty]
    [StringProperty(Indexed = true)]
    string FileName { get; set; }

    [FileProperty]
    FileValue File { get; set; }
}

// ────────────────────────────────────────────────────────────────────────────
//  Embedded types
// ────────────────────────────────────────────────────────────────────────────

public class OpeningHours {
    public Guid Id { get; set; }
    public string DayCode { get; set; } = string.Empty;   // "mon" … "sun"
    public TimeSpan Opens { get; set; }
    public TimeSpan Closes { get; set; }
}

// ────────────────────────────────────────────────────────────────────────────
//  Relations
// ────────────────────────────────────────────────────────────────────────────

public class EventsAtVenue : OneToMany<IVenue, IEvent> {
    public class Venue  : One { }
    public class Events : Many { }
}

public class OrganizerEvents : OneToMany<IOrganizer, IEvent> {
    public class Host   : One { }
    public class Events : Many { }
}

public class Attendance : ManyToMany<IEvent, IAttendee> {
    public class Attendees : ManyTo { }
    public class Events    : ManyFrom { }
}

public class Friends : ManyMany<IAttendee> {
    public class Peers : Many { }
}

[Relation(DisallowCircularReferences = true)]
public class VenueTree : OneToMany<IVenue, IVenue> {
    public class Parent   : One { }
    public class Children : Many { }
}

11.1 The same model with facet interfaces#

The model above declares everything directly on each type, which keeps each one readable in isolation. In a real project you would factor the cross-cutting properties into facet interfaces, as in §2. Notice how much duplication disappears — and what it buys you at query time.

One deliberate change along the way: Venue.Name, Event.Title and Attendee.FullName all become a single INamedNode.Title. Unifying the name is the price of the shared facet, and it is usually worth paying — it is what makes a single search box and a single "recently changed" feed possible.

// ── Facets ──────────────────────────────────────────────────────────────────

public interface INamedNode {
    Guid Id { get; set; }
    NodeMeta Meta { get; }

    [DisplayNameProperty]
    [StringProperty(Indexed = true, IndexedByWords = true, PrefixSearch = true)]
    string Title { get; set; }

    [AddressProperty]
    [StringProperty(Indexed = true, UniqueValues = true)]
    string Slug { get; set; }

    [CreatedUtcProperty] DateTime CreatedUtc { get; set; }
    [ChangedUtcProperty] DateTime ChangedUtc { get; set; }
}

public interface IDescribed {
    [HtmlProperty(IndexedByWords = true, IndexedBySemantic = true)]
    string Description { get; set; }
}

public interface ILocatable {
    [GeoCoordinateProperty(Indexed = true)]
    GeoCoordinate Location { get; set; }

    [StringProperty(Indexed = true, MaxLength = 2)]
    string CountryCode { get; set; }
}

public interface ITagged {
    [StringArrayProperty(Indexed = true)]
    string[] Tags { get; set; }
}

// ── Composed node types ─────────────────────────────────────────────────────

public interface IVenue : INamedNode, IDescribed, ILocatable, ITagged {
    [IntegerProperty(Indexed = true, MinValue = 0)] int Capacity { get; set; }
    [IntegerProperty(Indexed = true)]               VenueKind Kind { get; set; }
    [BooleanProperty(Indexed = true)]               bool IsAccessible { get; set; }
    [FileProperty]                                  FileValue Photo { get; set; }

    [EmbeddedMapProperty(KeyProperty = nameof(OpeningHours.DayCode))]
    EmbeddedMap<string, OpeningHours> Hours { get; }

    VenueTree.Parent     Parent { get; }
    VenueTree.Children   Halls  { get; }
    EventsAtVenue.Events Events { get; }
}

public interface IEvent : INamedNode, IDescribed, ITagged {
    [DateTimeProperty(Indexed = true)]  DateTime StartsUtc { get; set; }
    [TimeSpanProperty(Indexed = true)]  TimeSpan Duration { get; set; }
    [IntegerProperty(Indexed = true)]   EventStatus Status { get; set; }

    [DecimalProperty(Indexed = true, MinValue = "0", DefaultValue = "0",
                     FacetRangePowerBase = 2.0, FacetRangeCount = 6)]
    decimal Price { get; set; }

    [ReferenceProperty(Indexed = true)]  Reference<IMediaAsset>  Cover    { get; }
    [ReferencesProperty(Indexed = true)] References<IOrganizer>  Sponsors { get; }

    EventsAtVenue.Venue  Venue     { get; }
    OrganizerEvents.Host Host      { get; }
    Attendance.Attendees Attendees { get; }
}

public interface IAttendee : INamedNode, ILocatable {
    [StringProperty(StringType = StringValueType.Email, Indexed = true, UniqueValues = true)]
    string Email { get; set; }

    Attendance.Events Attending { get; }
    Friends.Peers     Friends   { get; }
}

public interface IOrganizer : INamedNode, IDescribed {
    [StringProperty(StringType = StringValueType.Email, UniqueValues = true)]
    string ContactEmail { get; set; }

    OrganizerEvents.Events Events { get; }
}

public interface IMediaAsset : INamedNode {
    [FileProperty] FileValue File { get; set; }
}

Id, Meta, Title, Slug and the timestamps are now written once, in INamedNode, and the whole model inherits them. Location is written once and shared by venues and attendees.

And the payoff at query time:

// One search box across venues, events, organizers and assets
db.Query<INamedNode>().WhereSearch("nordic jazz", semanticRatio: 0.5).Execute();

// One map query across venues and attendees
db.Query<ILocatable>().Where(x => x.Location.IsWithin(oslo, 5_000)).Execute();

// One tag cloud across venues and events
db.Query<ITagged>().Facets().AddValueFacet(x => x.Tags).Execute();

// Global "recently changed" feed
db.Query<INamedNode>().OrderByDescending(x => x.ChangedUtc).Page(0, 50).Execute();

Each of those is a single indexed query. Without shared facet interfaces they would be one query per concrete type, merged and re-sorted in memory — and re-merged every time you add a type.

Watch the two constraints: because INamedNode declares Title, no other facet may declare Title too, and no composed type may redeclare it.

12. Registering the model & the admin UI#

Server-hosted (the usual case)#

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.AddRelatudeDB(options => {
    // options.FileConverters.Add(new SkiaImageConverter());
    // options.FileConverters.Add(new FFMpegVideoConverter());
});

var app = builder.Build();

app.MapGet("/", (RelatudeDBContext ctx) => $"{ctx.Database.Count()} nodes.");

app.UseRelatudeDB();   // mounts the admin UI at /relatude.db
app.Run();

AddRelatudeDB lives in the default global namespace — no using required. RelatudeDBContext is injected by DI; ctx.Database is the NodeStore, which is the API surface for everything below.

relatude.db.json#

Everything that is not code lives in relatude.db.json: storage backends, index engines, file stores, AI providers, admin credentials and datamodel sources. It sits in the root data folder — ServerOptions.DefaultDataFolderPath resolved against the app's content root, so by default beside the app — with relatude.db/ (the data) and relatude.db.temp/ (scratch, emptied at every start) as siblings.

If the file is missing it is created for you, from a default that points at the bundled demo model. A store full of Relatude.DB.Demo.Models types means exactly that: the file was never configured. The admin UI edits the same file and rewrites it wholesale, so comments in a hand-written file survive being read but not being saved from the UI.

One server holds N containers (databases); each container names the storage it uses by id:

{
  "MasterUserName": "admin",           // lowercase — see below
  "MasterPassword": "…",               // plain text; prefer injecting these, see OnServerSettingsInit
  "TokenEncryptionSecret": "…",        // without it, logins do not survive a restart
  "DefaultStoreId": "8f6b…",           // which container ctx.Database resolves to
  "DBAdminUIUrlPath": "/relatude.db",  // overrides the argument passed to UseRelatudeDB()

  "ContainerSettings": [
    {
      "Id": "8f6b…",
      "Name": "MyDatabase",
      "AutoOpen": true,
      "WaitUntilOpen": false,          // true blocks startup until the store is open

      "IOSettings": [                  // storage backends this container may use
        { "Id": "1a2b…", "Name": "Local disk", "IOType": "LocalDisk", "Path": "relatude.db" }
      ],
      "IoDatabase": "1a2b…",           // the transaction log — the source of truth
      "IoIndexes": null,               // persisted index files; falls back to IoDatabase
      "IoBackup": "1a2b…",
      "IoLog": "1a2b…",
      "AISettings": null,              // per-database AI provider; required for semantic search

      "FileStoreSettings": [
        { "Id": "…", "IoProviderId": "1a2b…", "StoreType": "MultiFile", "MultiFileFolderDepth": 2 }
      ],

      "DatamodelSources": [ /* below */ ],
      "LocalSettings": { /* the engine knobs: index engines, flushing, caches, backups */ }
    }
  ]
}

An IOSettings entry is a storage backend (Memory, LocalDisk or AzureBlobStorage); the Io… fields point at one by id. That indirection is what lets the log, the indexes and the file bytes live in different places without repeating connection details.

LocalSettings is the per-store engine configuration — the index engines (ValueIndexes, TextIndexes, VectorIndexes and the Default…Index ids that pick among them), the disk-flush policy, cache sizes, auto-backup retention, EnableTextIndexByDefault, DefaultCultureCode, and so on. Every field has a working default; leave it out until you need it. §12.1 documents every key in the file, object by object, with its default.

AISettings configures the container's own AI provider (embeddings and completions) and its semantic index. TypeName picks the provider; all of them are dependency-free implementations that ship inside Relatude.DB.Server itself (assembly Relatude.DB.Providers), so there is nothing extra to install: AzureAIProvider (Azure OpenAI, the default) with ServiceUrl as the resource endpoint and deployment names in CompletionModel/EmbeddingModel; OpenAIProvider for OpenAI or any OpenAI-compatible endpoint (ServiceUrl defaults to https://api.openai.com/v1 — point it at Mistral, Groq, Ollama or similar); and AnthropicAIProvider for Claude completions, which pairs with an OpenAI-compatible EmbeddingServiceUrl/EmbeddingApiKey/EmbeddingModel since Anthropic has no embeddings API. The vector index engine itself is not an AI setting: it is chosen in LocalSettings like the other index kinds (VectorIndexes and DefaultVectorIndex, see below), and only exists on a container that has AISettings.

12.1 Every setting in relatude.db.json#

The file is one JSON object, deserialised into RelatudeDBServerSettings with case-insensitive property names, enums written as names ("LocalDisk", "Native") and // comments allowed on read. Every field has a working default; omit what you are not changing. The tables below list all of them, grouped by the object they sit on, with the default the engine uses when the key is absent.

Two conventions run through the whole file. Objects are wired together by Id: a container names its storage backends and file stores by their Guid rather than repeating connection details, which is what lets the log, the index files and the file bytes live in three different places. And relative paths resolve against the root data folder (ServerOptions.DefaultDataFolderPath against the content root — the content root itself unless you change it), never against the current directory.

Server level#

{
  "Id": "3f9c...",
  "Name": "Relatude.DB Server",
  "MasterUserName": "admin",
  "MasterPassword": "…",
  "TokenEncryptionSecret": "…",
  "DefaultStoreId": "8f6b…",
  "ContainerSettings": [ /* one entry per database */ ]
}

Authentication. These govern the admin UI only; they have nothing to do with your application's own users.

Container level#

{
  "Id": "8f6b…",
  "Name": "MyDatabase",
  "AutoOpen": true,
  "WaitUntilOpen": false,
  "IOSettings": [ … ],
  "IoDatabase": "1a2b…",
  "FileStoreSettings": [ … ],
  "DatamodelSources": [ … ],
  "AISettings": null,
  "LocalSettings": { … }
}

IOSettings — a storage backend#

{ "Id": "1a2b…", "Name": "Local disk", "IOType": "LocalDisk", "Path": "relatude.db" }
{ "Id": "9d8c…", "Name": "Azure",      "IOType": "AzureBlobStorage",
  "BlobConnectionString": "…", "BlobContainerName": "mydb", "LockBlob": true }
{ "Id": "0000…", "Name": "In memory",  "IOType": "Memory" }

Within a LocalDisk folder the engine keeps its own layout — data/, state/, backup/, log/ and an index folder with one subfolder per engine — so several roles can share one backend without colliding.

FileStoreSettings — where file bytes live#

{ "Id": "c4d5…", "IoProviderId": "1a2b…", "StoreType": "MultiFile", "MultiFileFolderDepth": 2 }

Leave the array empty and the store creates an implicit default store on IoDatabase: a MultiFile store, one file per upload.

AISettings — embeddings, completions and the vector index#

"AISettings": {
  "TypeName": "AzureAIProvider",
  "ServiceUrl": "https://my-resource.openai.azure.com",
  "ApiKey": "…",
  "EmbeddingModel": "text-embedding-3-small",
  "CompletionModel": "gpt-4o-mini"
}

LocalSettings — the engine#

Every key here has a working default. The groups below are ordered by how often you actually touch them.

Indexing. What gets indexed at all, and by which engine. A fresh relatude.db.json comes with one Native value engine and one Native text engine, and the defaults pointing at them:

"LocalSettings": {
  "ValueIndexes":  [ { "Id": "4d1f…", "TypeName": "Native", "MaxMemoryUsageInMb": 256 } ],
  "TextIndexes":   [ { "Id": "9b2c…", "TypeName": "Native", "MaxMemoryUsageInMb": 256 } ],
  "VectorIndexes": [ { "Id": "e7a0…", "TypeName": "HNSW",   "MaxMemoryUsageInMb": 512 } ],
  "DefaultValueIndex":  "4d1f…",
  "DefaultTextIndex":   "9b2c…",
  "DefaultVectorIndex": "00000000-0000-0000-0000-000000000000"   // the memory index; the HNSW engine is ready to be chosen
}

Culture, access and files.

Durability. How eagerly writes reach the disk. The defaults trade a sub-second window for throughput; nothing here risks corruption, only the last fraction of a second of writes.

State snapshots. How fast the next start is. A snapshot lets the engine skip replaying the log from the beginning; without one, opening is a full replay.

Backups. Off by default; the admin UI has a one-click backup either way.

Log truncation. The transaction log grows forever unless something compacts it.

Caches. Sized in gigabytes, and both are upper bounds rather than reservations.

Background tasks and diagnostics.

Overriding settings from configuration#

Any setting in relatude.db.json can be overridden from standard ASP.NET configuration. At startup the server reads the RelatudeDB section — from appsettings.json, appsettings.{Environment}.json, environment variables, user secrets, or any other configuration source the host has — and merges it over the loaded file. The section has the same shape as relatude.db.json; there is no separate schema to learn.

// appsettings.Development.json
{
  "RelatudeDB": {
    "MasterUserName": "admin",
    "ContainerSettings": [
      { "LocalSettings": { "AutoBackUp": false } }
    ]
  }
}

The same keys work as environment variables (RelatudeDB__MasterPassword=…) and as user secrets (dotnet user-secrets set RelatudeDB:TokenEncryptionSecret …). That is the intended home for credentials: user secrets in development, environment variables or a vault in production, and relatude.db.json never holds them at all.

The merge rules:

• Objects merge key by key; scalars replace. Keys are case-insensitive, and values are coerced to the setting's type ("true", "2.5", enum names).
• Array elements are matched on Id when the overlay element gives one, on position otherwise; unmatched elements are appended. An overlay can change and add, but not remove — and it cannot set a value to null (a JSON null is invisible to the configuration system).
• A key that matches no setting, a read-only setting, or a value that does not parse is reported as a warning at startup and skipped. A typo never fails the boot, but it is never silent either.
• The startup log lists every overridden key path — paths only, never values. Overriding Id or DefaultStoreId re-identifies an object instead of reconfiguring it, and draws an explicit warning.

Overridden values never reach the file. The admin UI saves settings back to relatude.db.json wholesale; before that write the server restores every overridden key to the value the file had, so a secret supplied through configuration is not baked into the file by the next save. The flip side: while a key is overridden, editing it in the admin UI has no lasting effect — configuration wins again on the next load. The startup log tells you which keys are in that state.

The overlay is applied after the settings file is read and before OnServerSettingsInit fires, so every callback sees the merged settings. ServerOptions.ConfigurationSectionName renames the section; set it to null to turn the overlay off. A custom SettingsLoader is composed with, not replaced: the overlay applies to whatever the loader returns.

Options and events in Program.cs#

ServerOptions owns what only code can express — the file converters, the folder paths, an alternative settings store, and the lifecycle callbacks:

builder.AddRelatudeDB(options => {

    // Image and video conversion does not work without these
    options.FileConverters.Add(new SkiaImageConverter(1));
    options.FileConverters.Add(new FFMpegVideoConverter());

    options.DefaultDataFolderPath = "data";          // relative to the content root, or absolute
    options.DefaultTempFolderPath = "data/tmp";
    options.SettingsLoader = new MySettingsLoader();  // replaces relatude.db.json entirely

    // Secrets belong in the RelatudeDB configuration section (previous section) — it is merged in
    // automatically and stripped again before saves. This callback also works, but what it sets is
    // written back to relatude.db.json when the admin UI saves settings.
    options.OnServerSettingsInit = s => {
        s.TokenCookieName = "MyToken";
    };

    options.OnDatamodelInit = (dm, container) => dm.AddNamespace<IVenue>();
    options.OnStoreInit = db => db.RegisterTransactionPlugin(new AuditPlugin());
    options.OnStoreOpenBackground = db => Seeder.SeedIfEmpty(db);
});

They fire in this order:

Two things about these are worth knowing before you rely on them. Every callback is wrapped in a try/catch by the server: an exception inside one is written to the startup log and swallowed, so a callback that silently did nothing is a startup-log question rather than a crash. And seeding belongs in OnStoreOpenBackground — OnStoreOpen blocks the open, and while a store is opening every request gets a 503 progress page.

Two ways to register a datamodel#

The JSON sources load first, then OnDatamodelInit runs against the same Datamodel object — so the two are additive rather than alternatives.

From relatude.db.json, when the model must change without a rebuild, or differs between deployments of the same binary:

"DatamodelSources": [
  {
    "Id": "8a3f...",                   // required, and unique across the sources
    "Name": "VenueApp",
    "Type": "TypeReference",           // see the table below
    "FileFormat": "Json",              // TextFiles: what the files hold, Json or CSharpCode
    "Namespace": "VenueApp.Models",    // one namespace, or a pattern: "VenueApp.Models.*" takes it and everything under it
    "Reference": "VenueApp",           // assembly name; null means the current project (the entry assembly)
    "Filepath": null,                  // file or folder, for the file-based types
    "FileIO": null,                    // legacy: read a JSON model file through an IO provider instead
    "SourceCodePath": null,            // TypeReference: the folder with the C# files, for the model editor
    "GenerateModelFile": false,        // TypeReference: the model editor owns that folder and regenerates it
    "Enabled": true,                   // false skips the source entirely
    "Color": null                      // the colour the admin UI marks this source's types with; null picks one from a palette
  }
]

Relative Filepath values resolve against the root data folder. Every source must carry a unique Id — it is what tags each type with its provenance, which is how the admin UI knows which source a type came from and which sources it may edit.

Color is the one setting nothing in the engine reads: it is the colour the admin UI marks this source's types and relations with, wherever they are listed — the model editor, the dashboard's content panel, the query page's type picker. Any CSS colour ("#2f7fd6", "teal"); left out, the source takes one from a ten-hue palette by its position in the list, which is what every source did before there was anything to set. It can be changed on the settings page while the database is open.

A TypeReference source is compiled into the application, so the admin UI's model editor can only write to it when GenerateModelFile is on and SourceCodePath names the folder the generated C# files go into (relative to the settings folder unless rooted, and inside the project that builds the assembly); the application then has to be rebuilt and restarted for the change to take effect. That folder belongs to the editor: activating a model deletes every file in it and generates one file per node type and relation, each starting with an // <auto-generated> comment saying it will be overwritten. Files in the folder without that comment are listed before the activation, which only goes ahead once they are given up — so point it at a folder of its own, not at the project root. (SourceCodePath without GenerateModelFile still works from a hand-edited settings file: the editor then rewrites the existing files in place and leaves files that hold no model types alone. The admin UI only offers the generated form.) In the editor's source form the assembly and namespace are comboboxes: the first assembly choice is the current project, and a scan lists the assemblies the running application can see, then the namespaces of the chosen one — scanned on request, since reflecting over every loaded assembly takes a moment. Under the form the editor lists what the chosen assembly and namespace would load, so a typo shows up before the database is reopened.

Enabled (true when absent) is a switch rather than a setting: a source turned off contributes nothing and is not registered on the model at all, so nothing it defines survives the next open, and nodes already stored under those types come back without the properties the types declared. Turning it back on restores the model exactly. Sources are edited from the admin UI under Settings → Data model → Model sources, and one added there starts turned off — an unfinished source would otherwise stop the database from opening, since every configured source is loaded and one that throws fails the open.

From Program.cs, which is the common case when the model ships with the app — refactor-safe, and it fails at compile time rather than at boot:

options.OnDatamodelInit = (dm, container) => {
    dm.AddNamespace<IVenue>();          // every node & relation type in IVenue's namespace
    dm.Add<IEvent>();                   // one type, plus everything it references
    dm.Add(typeof(IAttendee));
    dm.AddAssembly(typeof(IVenue).Assembly, "VenueApp.Models.Sub");
};

With more than one database, branch on the container the callback is given:

options.OnDatamodelInit = (dm, container) => {
    if (container.Name == "Catalog") dm.AddNamespace<IProduct>();
    else dm.AddNamespace<IAuditEntry>();
};

The static flag DatamodelSource.AutoDeduceRelations (off by default, and process wide — set it before the database opens) decides what happens to a plain node-typed property with no relation declared: off, it becomes a Reference/References; on, it is turned into an auto-created relation, which is the old behaviour. Leave it off in new models. Until September 2026 this was a per-source setting in relatude.db.json; a leftover "AutoDeduceRelations" key there is ignored.

Either way the server builds the datamodel, generates the proxy assembly and reloads, and from then on the model is rebuilt automatically whenever the assembly loads.

The admin UI#

The admin UI is not an optional extra — it is where the parts of Relatude.DB that are not code get configured. Your model lives in C#; the runtime lives in the admin UI. Worth knowing your way around it early.

app.UseRelatudeDB() mounts it at /relatude.db. Pass a path to move it:

app.UseRelatudeDB("/admin/db");

It has its own authentication, and nothing creates an admin user for you — but locally you do not need one. NoLoginRequiredForLocalhost defaults to true, so a request that really came from a browser on this machine reaches the admin UI without logging in at all; that is why it just works in development.

"Really came from this machine" is decided narrowly, and it is worth knowing where the line is. The connection's peer must be loopback, and the request must carry no sign of a reverse proxy — neither forwarded headers (X-Forwarded-For, Forwarded, X-Real-IP, X-ARR-LOG-ID and the platform-specific variants) nor a hosting environment that is always fronted, such as Azure App Service, IIS or Kubernetes. The reason is that a proxy on the same host makes every request arrive from loopback, so a loopback peer on its own cannot tell a local browser apart from the whole internet. Deployed behind a proxy, then, nothing is ever "localhost" and this setting stops applying — which is the point, but it means such a deployment needs real credentials and AllowMasterLoginOutsideLocalhost, or no one can get in at all. The server says so in its log the first time it refuses a request for that reason.

Away from localhost it is the opposite: AllowMasterLoginOutsideLocalhost defaults to false, which refuses both the login and any existing session cookie from a remote address. Turn it on deliberately, over HTTPS, and only after setting credentials. Set MasterUserName and MasterPassword in relatude.db.json, or better, in the RelatudeDB configuration section (user secrets, environment variables); until they are set, logging in throws "No master user configured on the server."

Three more details cost people time: the stored user name must be lowercase (the check lowercases the input before comparing), the password is compared verbatim and stored in plain text, and without TokenEncryptionSecret the server uses a random per-process key, so every restart invalidates every session cookie. Failed logins are rate-limited per IP and every attempt is answered after a randomised 300–400 ms delay, so a wrong password and an unknown user name are indistinguishable by timing.

What you do in it:

Two habits worth forming:

• Check the datamodel browser after any modelling change. It shows the parent chain of each type, so it is the fastest way to confirm that your facet interfaces (§2) actually landed as parent node types, and that a property you expected to be indexed really is.
• Middleware order matters. UseRelatudeDB installs the engine's own startup-progress and auth middleware, so call it after your own UseCors / UseHttpsRedirection / UseAuthentication.

Programmatic / embedded#

Outside the server host — tests, an embedded store, an import tool — you build the Datamodel yourself and hand it to the store:

var datamodel = new Datamodel();
datamodel.AddNamespace<IVenue>();        // every node & relation type in that namespace
// or, one at a time:
datamodel.Add<IEvent>();
datamodel.Add(typeof(IAttendee));

AddNamespace<T> scans the assembly containing T and adds every type whose namespace matches T's exactly, skipping enums, static classes and anything marked [Exclude]. Add<T> also pulls in every type T references, unless you pass includeAllReferencedModels: false. Adding to a datamodel that has already initialised throws — which is why OnDatamodelInit is the window for this when you are running under the server.

What the model builder validates#

At build time (you find out on startup):

• Non-interface node types must have a parameterless constructor.
• Two parent interfaces may not declare the same property name.
• Two classes may not declare the same property name — overriding is not supported.
• Nullable value types (int?, DateTime?, GeoCoordinate?) are not supported.
• Only these value types are allowed: bool, byte, int, long, double, float, decimal, DateTime, DateTimeOffset, Guid, TimeSpan, GeoCoordinate and any enum.
• Id must be Guid or string; the internal id must be int, long or string.
• Marker attributes must sit on a compatible type — [DisplayNameProperty] and [AddressProperty] on string, [CreatedUtcProperty] and [ChangedUtcProperty] on DateTime.
• Two types with the same [Node(Id = …)] Guid but different full names → error.
• A relation class must have the right number of nested side classes for its shape.

At write time (the transaction fails):

• LegalValues / RegularExpression / min/max / length bounds.
• MinNoInstances / MaxNoInstances per type.
• UniqueValues = true uniqueness across the type.
• DisallowCircularReferences = true acyclicity on self-referential relations.

Do not redefine the native types#

The engine ships its own model in Relatude.DB.Native.Models — ISystemUser, ISystemUserGroup, ISystemCollection, ISystemCulture. They back the admin UI, auth and culture handling. If your domain needs a "user", model your own type and relate it to ISystemUser if you need the link.

Part II — Writing data#

13. Create, insert, update, delete#

db below is ctx.Database, a NodeStore.

// CREATE — hands you a proxy that tracks changes
var venue = db.Create<IVenue>();
venue.Name = "Sentrum Scene";
venue.Slug = "sentrum-scene";
venue.Location = new GeoCoordinate(59.9200, 10.7480);
venue.Capacity = 1750;
venue.Kind = VenueKind.Indoor;
venue.IsAccessible = true;

db.Insert(venue);                    // returns TransactionResult

// …or in one call:
var ev = db.CreateAndInsert<IEvent>((e, t) => {
    e.Title     = "Winter Session";
    e.StartsUtc = new DateTime(2026, 11, 14, 19, 0, 0, DateTimeKind.Utc);
    e.Duration  = TimeSpan.FromHours(3);
    e.Price     = 450m;
    e.Status    = EventStatus.Published;
    e.Tags      = ["live", "electronic"];
});