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 10+.

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. The one exception is [PropertyOverride], which gives that class its own default, text index or display name setting for the property, or asks for its value index or a facet (§3.1).

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 (take it from the base types, else the database default), True, False. TextIndex, SemanticIndex and InstantTextIndexing are inherited: see §3.1. [Node] also accepts MinNoInstances / MaxNoInstances to constrain how many nodes of the type, its descendants included, may exist - see Validation happens on write.

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 as a whole and is rolled back, rather than silently storing bad data. The values already stored are never checked again: tightening a rule does not stop the database from opening, but a node whose value breaks the new rule cannot be saved until the value is changed.

• RegularExpression must match every value written, the empty value too - a pattern such as ^[a-z0-9-]+$ therefore makes the value required. Allow the empty value in the pattern when it is optional (^([a-z0-9-]+)?$). It is a match anywhere in the value unless anchored with ^ and $.
• LegalValues on a string is compared ordinally. The empty value is always allowed - it is what a node holds before the value is set - so add MinLength = 1 to require one. The admin UI edits such a property with a list of the values.
• LegalValues on an integer holds a plain int to the listed values. An enum is not held to its members, which the engine fills in for display: a [Flags] combination, or a member added in a newer version of the application, is still a value of it.
• MinNoInstances / MaxNoInstances on [Node] count the nodes of the type and of every type inheriting from it, whatever their meta says (unpublished, hidden or marked deleted). The counts are checked on what the whole transaction leaves, so one that deletes a node and inserts its replacement passes at the limit, and only in the direction the transaction moves them: a type may start below its minimum (with MinNoInstances = 1 the last node cannot be deleted, while the first can always be inserted), and a type with more nodes than a maximum set later keeps them and can still be updated and deleted from - it only refuses inserts.

3.1 Overriding attributes#

Sometimes the attribute you want to change is not yours to edit: the type comes from an assembly you do not build, the property is declared on a base interface other types share, or a default value has to change in production without a rebuild. Three layers decide what a type ends up with, and on one type a later layer wins over an earlier one:

1. Declared - the attributes on the member or type that declares it (or its JSON model file): everything above.
2. Overridden in code, on a derived type - a type sets its own value for a switch it inherits, or for one of the attributes of a property it inherits.
3. Overridden at runtime - the database's overrides, written by the data model editor and applied when the database opens, exactly as if the source said so.

The text search switches are inherited. TextIndex, SemanticIndex and InstantTextIndexing on [Node] go to the types inheriting from the type they are set on: a type that does not set one takes it from the most specific base type that does, and only then the database default (EnableTextIndexByDefault and friends, §12.1). Before October 2026 they applied to the one type they were set on.

[Node(TextIndex = BoolValue.True)]
public interface IContent { /* ... */ }        // every type implementing IContent is text indexed ...

[Node(TextIndex = BoolValue.False)]
public class InternalNote : IContent { /* ... */ } // ... except this one

Two base types that are not related and disagree cancel out: the type gets the database default, and the database logs a warning naming both. Set the switch on the type to choose. Semantic indexing needs the text index, so a type that is semantically indexed - by itself, a base type or the database default - stays text indexed whatever its TextIndex says.

An inherited property: [PropertyOverride]. A property has one declaration, but four of its attributes may differ between the types that have it, and a type can ask for its value index and for it to be a facet. A derived type sets these with [PropertyOverride], which offers those six and nothing else:

Anything left out - a switch left at BoolValue.Default, no DefaultValue, no TextIndexBoost - is what the base types say. The examples below share this base interface:

public enum ContentStatus { Draft = 0, Published = 1, Archived = 2 }

[Node(TextIndex = BoolValue.True)]
public interface IContent {
    Guid Id { get; set; }
    [StringProperty(DefaultValue = "Untitled", DisplayName = true)] string Title { get; set; }
    [StringProperty] string Subtitle { get; set; }
    [HtmlProperty] string Body { get; set; }
    [IntegerProperty(Indexed = true)] ContentStatus Status { get; set; }
}

On the type, naming the property. Name the inherited property with nameof, one attribute per property, each with as many of the four as you need:

[Node]
[PropertyOverride(nameof(IContent.Title), DefaultValue = "Untitled news", TextIndexBoost = 2)]
[PropertyOverride(nameof(IContent.Status), DefaultValue = ContentStatus.Published)]
public class NewsArticle : IContent {
    public Guid Id { get; set; }
    public string Title { get; set; } = "";
    public string Subtitle { get; set; } = "";
    public string Body { get; set; } = "";
    public ContentStatus Status { get; set; }
}

var news = db.Create<NewsArticle>();   // Title "Untitled news", Status Published

Every other type implementing IContent keeps "Untitled" and Draft. A news title also weighs more in search: it goes into the text index two extra times, while other types' titles go in once. An enum default is given as the enum value. A default is what db.Create<T>() starts a node with, and what a stored node reads for a property it has no value for. new NewsArticle() is plain C#, so it starts with the property initializers instead.

On the implementing member. A class that implements an interface property can put the attribute on its member and leave out the name. This is the one property attribute such a member can carry: other attributes there are ignored, since the interface defines the property (§2).

[Node]
public class Book : IContent {
    public Guid Id { get; set; }
    public string Title { get; set; } = "";
    [PropertyOverride(DisplayName = BoolValue.True)]   // a book shows as "Title Subtitle"
    public string Subtitle { get; set; } = "";
    public string Body { get; set; } = "";
    public ContentStatus Status { get; set; }
}

The display name joins the values of the display-name properties with spaces, so Book shows both values while other types show the title alone.

Turning one off. BoolValue.False and BoolValue.True work in both directions, so a type can also take back what its base types turn on:

// tickets are found by their title, but the body - customer details - stays out of search
[Node]
[PropertyOverride(nameof(IContent.Body), ExcludeFromTextIndex = BoolValue.True)]
public class SupportTicket : IContent { /* ... */ }

Down a class chain, and on interfaces. An override reaches every type that inherits from the type it is set on, and a more specific type can override it again. Decimals, dates, durations and guids are given as strings, in the formats the property attributes use (Numbers):

[Node]
public class Product {
    public Guid Id { get; set; }
    [StringProperty(DisplayName = true)] public string Name { get; set; } = "";
    [DecimalProperty(DefaultValue = "0", Indexed = true)] public decimal Price { get; set; }
}

[Node]
[PropertyOverride(nameof(Product.Price), DefaultValue = "25")]
public class GiftCard : Product { }

[Node]
public class DigitalGiftCard : GiftCard { }       // 25, from GiftCard

[Node]
[PropertyOverride(nameof(Product.Price), DefaultValue = "50")]
public class PremiumGiftCard : GiftCard { }       // 50: the more specific type wins

// an interface carries overrides too: every type implementing it starts published
[Node]
[PropertyOverride(nameof(IContent.Status), DefaultValue = ContentStatus.Published)]
public interface IPublishedOnCreate : IContent { }

Two base types that are not related and disagree cancel out, as with the switches above. The type gets what the declaration says, and the database logs a warning naming both. To choose, set the value on the type itself. Everything else about a property is one setting wherever the property is used: it has one value index, one word index and one set of rules. A type can ask for the value index and for a facet, but the rest stays with the declaration, and only an override on the declaring type changes it (the table below).

Asking for the value index, or a facet. A type that filters, sorts or facets on a property its base type does not index asks for the index with Indexed. A property its base type keeps out of the facets (NotFacet) it asks to make a facet with NotFacet = BoolValue.False - NotFacet is an opt-out, so false is the value that asks:

// declared in a package: the part number is not indexed there, and the maker is no facet
[Node]
public class Part {
    public Guid Id { get; set; }
    [StringProperty] public string PartNumber { get; set; } = "";
    [StringProperty(Indexed = true, NotFacet = true)] public string Maker { get; set; } = "";
}

// the workshop looks spare parts up by number and narrows them down by maker
[Node]
[PropertyOverride(nameof(Part.PartNumber), Indexed = BoolValue.True)]
[PropertyOverride(nameof(Part.Maker), NotFacet = BoolValue.False)]
public class SparePart : Part { }

var part = db.Query<SparePart>().Where(p => p.PartNumber == "A-1001").Execute(); // uses the index
var makers = db.Query<SparePart>().Facets().AddValueFacet(nameof(Part.Maker)).Execute();

A facet counts the values in the value index, so it needs one: asking for a facet on a property without an index does nothing, and the database logs a warning. Ask for both when the base type has neither.

A property has one value index, so the type gets the property's index, not one of its own. That index holds the part number of every node that has the property, Part and the other types inheriting it included. A property is indexed when its declaration says so or any type that has it asks. A type that sets BoolValue.False only takes back its own request: it cannot take away an index the declaration or another type wants, and the database logs a warning when a type says no to an index that stays. To drop an index, override Indexed on the declaring type (the table below). Asking for an index, or no longer asking, changes the model, so the database rebuilds its state and indexes from the log at the next open.

A facet works the same way, with the values turned around. The property has one set of facet counts, so Maker becomes a facet for Part and every other type that has it, not only for SparePart. A type that sets NotFacet = BoolValue.True only takes back its own request, and a facet the declaration has stays a facet.

Mistakes stop the build. A [PropertyOverride] that cannot apply fails the model build at startup. The message names the type and the property. The build fails when the attribute:

• names a property the type declares itself. Set that property's attributes on its own property attribute instead.
• names no member of the type (a typo: use nameof), or names a member marked [Exclude].
• names a system member: the id, NodeMeta, the created/changed dates, or the display-name or address marker. None of these has attributes to override.
• gives a DefaultValue that does not convert to the property's type ("a lot" for a decimal), or gives a default to a property that has none to set (arrays, files, references and the like).
• sits on a type without naming the property, or sits on a member and names a different property.
• is one of two [PropertyOverride]s for the same property on one type. Combine them into one.

[Node]
[PropertyOverride(nameof(Product.Id), DefaultValue = "x")]        // fails: Id is a system member
[PropertyOverride(nameof(Product.Price), DefaultValue = "a lot")] // fails: not a decimal
public class BrokenGiftCard : Product { }

Overrides in the database are more forgiving (below): one that cannot apply is skipped with a warning, so it never stops the database from opening.

TextIndexBoost on [Node] is not in the list: the engine does not use it yet.

At runtime: the data model editor. The editor (admin UI, Models) writes a change into the source that defines it. Where that source cannot be written - classes compiled into an assembly without a source code folder, types registered in OnDatamodelInit - the fields that can be overridden stay open, and what is set in them is saved as an override. Each field says where its value comes from (overridden, own, from IContent), and the arrow beside an override takes it away. An inherited property opens as the derived type sees it, with its four per-type attributes open for that type, and Indexed and No facet to ask for the property's value index and facet (asked by names the other types that do). The Sources view lists every override beside what the source says. Activating saves them for this installation and reopens the database; the nodes of a type whose indexed text changed are queued for text indexing, and a type whose text indexing is turned off has its text taken out of the index first.

SHARED and THIS SERVER. A database keeps its overrides in two files, the way the settings are kept in relatude.db.json and relatude.db.overrides.json (§12):

When the database opens, THIS SERVER is merged over SHARED. A value on THIS SERVER replaces the SHARED value. null takes the SHARED value away, so the attribute follows the source again on this installation. Activating writes only the THIS SERVER file, and only what differs from SHARED: an override set back to the SHARED value leaves the file.

// relatude.data/overrides/datamodel.overrides.json: THIS SERVER, this installation's
{
  "NodeTypes": {
    "3ad77060-788d-21b2-31c1-4305dcae3437": {
      "Name": "Shop.Models.Product",
      "TextIndex": null,                  // SHARED says false; here the source decides
      "Properties": {
        "8b1aa6c4-205e-740c-73ca-26d1e39111dc": { "Name": "Price", "Indexed": true, "DefaultValue": 0 }
      }
    }
  }
}

The SHARED file has the same shape, without the nulls. Both are keyed by ids, with names beside them for reading. In the editor every overridden field is tagged with where its value is: shared, this server, or this server · removed for a SHARED value taken away here; the tooltip names the file, and the arrow beside the field takes one file away at a time.

Moving overrides into SHARED. Choose Move to shared at the top right of the model editor. The dialog lists the THIS SERVER file entry by entry, beside what SHARED says. Select overrides and choose Move into shared: they are written into the SHARED file and removed from THIS SERVER. Nothing in force changes, so the database is not reopened. Then commit the SHARED file. A moved null removes the value from SHARED. Discard puts the SHARED value back in the draft (or the source's, where SHARED has none), to be activated like any other change. Unactivated changes in the draft are not on THIS SERVER, so activate them before moving them.

Move where the application runs from its project folder, in the Development environment: there relatude.settings is the folder in source control. On a deployed server it is the deployed copy, and the next deployment replaces it, with whatever was moved into it. The dialog warns about this outside Development. Download shared file gives the file with the selected overrides moved in, without changing anything, so you can commit it by hand.

The SHARED file is found by the database's short name, so give the short name in relatude.db.json. A short name saved on one installation from the settings page lands in relatude.db.overrides.json, and that installation then reads other SHARED files than the rest. The settings page and the start-up log say so.

An override whose type or property is gone, a value that does not parse, an attribute that cannot be overridden: each is skipped with a warning in the log and in the editor, never a reason for the database not to open. From code, set Datamodel.Overrides before the store is created - the store applies them as it opens.

Two things worth knowing before changing a value at runtime:

• A default is late bound. A node with no value stored for a property reads the current default, so a new default reaches nodes that never had a value - stored before the property existed, or created without setting it. Stored values are never touched. The editor warns when the type has nodes; if the property is indexed, queries on it may not see the new default for those nodes until the indexes are rebuilt.
• Rules apply to new writes. A tighter MaxLength or MinValue does not check the values already stored. Turning Indexed or IndexedByWords on builds the index from the log at the next open.

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.

Querying by the node's own dates#

CreatedUtc and ChangedUtc are indexed for every node of every type — a class does not have to map them to members of its own. Refer to them through NodeMeta:

// recently changed, on any type - the base type included
db.Query<IArticle>().OrderByMetaDescending(m => m.ChangedUtc).Page(0, 50).Execute();
db.Query<IArticle>().WhereMeta(m => m.CreatedUtc >= since).Count();

A class that maps them answers the same queries through its own members — x.ChangedUtc on a [ChangedUtcProperty] member, or x.Meta.ChangedUtc on its NodeMeta — and they use the same index. In a query string the two are the system properties _createdUtc and _changedUtc of every type: Where("n => n._changedUtc > " + since.Ticks). The indexes live in the engine DefaultValueIndex names, like any other value index (§12.1). The rest of NodeMeta is not indexed and cannot be queried; for a node with revisions the published revisions decide (the first creation, the last change).

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.

Seeing them#

The admin UI's query page has a Map view: pick a GeoCoordinate property and the result set — the same one the search box and the facets are already narrowing — is drawn on a world map or on a globe. A pin or a dot per node (coloured by a second property, as the visual pivot colours its cards), a heat field, one bubble per patch of the map with a count in it, or every country shaded by how many nodes it holds. Nodes whose coordinate is Empty are simply not on it, and the view says how many those were.

An indexed property is read straight from the index there, so a map of a million nodes reads no nodes at all; an unindexed one has to be read node by node, which is one more reason to index a property you intend to look at.

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 relatude.settings/ below the root data folder — ServerOptions.DefaultDataFolderPath resolved against the app's content root, so by default relatude.settings/relatude.db.json in the app's own folder, with relatude.data/ (the data) and relatude.data.temp/ (scratch, emptied at every start) beside relatude.settings/. Relative paths in the file still resolve against the root data folder, not against the folder the file is in. The Web SDK publishes the file like any other .json in the project. The same folder holds the other files every installation shares: the definitions of custom logs (§32.1) and the shared datamodel overrides (§3.1). The folder is part of the application, kept in source control and deployed with it. relatude.data/ and relatude.data.temp/ are the opposite: they belong to the installation, so they are never committed — a typical .gitignore leaves them out — and the project file excludes them, so that a publish does not deploy them either. §12.2 sets out what goes where, and what stays with an installation.

Older versions kept the file in the root data folder itself, and for a while in relatude.settings/db/. At its first start the server moves such a file into relatude.settings/ — the text as it is, comments and all — and says so in the start-up log. A move that fails (a read-only deployment, a lock) does not stop the start: the file is read and written where it is, a warning says why, and the next start tries again. When an older place has a file as well, only relatude.settings/relatude.db.json is read and the start-up log warns about the other one; delete it once anything in it that still matters is in the new file.

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.data" }
      ],
      "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": [           // a new installation's: one copy per content, SHA256
        { "Id": "c4d5…", "IoProviderId": "1a2b…", "StoreType": "MultiFile", "MultiFileFolderDepth": 2,
          "SameHashSameFile": true, "HashAlgorithm": "SHA256" }
      ],

      "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. There is also RelatudeServices, which needs no account with an AI vendor at all: it calls the hosted Relatude AI service, which holds the vendor credentials and meters every call against your Relatude license (§35). On a server it pays with the installation's own API key, so ApiKey is only needed in a store built from code, and EmbeddingModel / CompletionModel are model keys the service publishes rather than vendor model names. The license has to carry the credit account each kind of call is charged to, with a balance: ai_embeddings for embeddings and ai_completion for completions (no feature is needed). A refusal (no such account, no credits, too many calls) comes back as an error naming the reason. 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.

Relatude Services. The account an installation may use for hosted AI, imaging, files to text and text messages, and for signing in to the admin UI (§35). None of it is needed: with no ApiKey, nothing is charged and nothing is reported.

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.data" }
{ "Id": "9d8c…", "Name": "Azure",      "IOType": "AzureBlobStorage",
  "BlobConnectionString": "…", "BlobContainerName": "mydb", "LockBlob": true }
{ "Id": "0000…", "Name": "In memory",  "IOType": "Memory" }

Blob leases. A lease lasts 60 seconds and is renewed in the background for as long as the stream is open, and it is let go of when the last stream on the blob closes - also when the close fails, or when the open fails half-way. A process that dies without letting go therefore blocks its blobs for at most a minute: an open that finds a blob leased waits up to 75 seconds for it, and then fails with a FileLockedException, which the startup restart treats as a lock, not as corruption. Readers of one blob in the same process share its lease. A write that finds its lease expired - the process was paused past it - renews it and carries on, as long as nobody touched the blob meanwhile; if another process has taken it, the write fails instead. Earlier versions leased for ever and could leave such a lease behind, which then blocked every open of that blob for good. To release them, open Files in the admin UI on the storage and press the Leases button (the open lock): it lists the leased blobs and breaks every lease this server does not hold itself. Break them only when no other instance uses the storage.

Within a LocalDisk folder the engine keeps its own layout — data/, state/, backup/, logs/ 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,
  "SameHashSameFile": true, "HashAlgorithm": "SHA256" }

A new installation gets this store, named as LocalSettings.DefaultFileStore: the server's default settings, relatude new / relatude init, and a database added under Databases in the admin UI all write one. A store added under Settings › FileValue providers, or made in code with new FileStoreSettings() or FileStoreSettings.CreateMultiFile(ioProviderId), also starts with SameHashSameFile on and SHA256.

"When absent" is what a store gets when its JSON leaves the key out: a store written before these two settings existed, in relatude.db.json, the overrides file or the RelatudeDB configuration section, keeps MD5 and one copy per upload rather than changing behaviour on upgrade. A SingleFile store ignores both: its container format records an MD5 checksum per file and never shares copies.

Leave the array empty and the store creates an implicit default store on IoDatabase: a MultiFile store, one file per upload, MD5. A database that already runs on it keeps it as it is. Files record the store they went into, and the implicit one's id is the empty guid: when a configured store is named as DefaultFileStore later, new uploads go there and the files already uploaded are still read from the implicit store.

Moving files to another store, or bringing old files up to date#

Changing the default store, or turning on SameHashSameFile or SHA256, only affects new uploads. To move the files already stored, use Storage › File storage › Rewrite files… in the admin UI. Pick the store to write the files into, and how it writes them: the hash (MD5 or SHA256) and Same hash, same file. Those two are the store's own settings - changing them in the dialog saves them, and the open store writes new uploads that way from then on, without a reopen. They cannot be chosen for the implicit store, for a SingleFile store, or where configuration or code decides them. The job runs in the background while the database stays in use, and its progress can be minimized to the top bar like the other file jobs.

• Every file that belongs in the store - the files of the properties whose uploads go there: the default store, or the store a file property names - is written into it, wherever it is stored now. Files of properties that upload into another store stay where they are. A store nothing uploads into has nothing that belongs in it; make it the default first.
• A file stored elsewhere gets a copy written by the target store, with that store's hash, layout and, where it keeps one copy per content, sharing. Revisions and embedded objects are included. A stored file that several values share is copied once.
• The name, image size, meta data and extracted text stay the same, and nothing is re-indexed.
• Each node is updated under its own lock. A value that changed while its file was being copied (a new upload, say) is left alone.
• A file already in the store is rewritten only where the store would now write it differently: a hash of the other algorithm, or a file not yet kept by its hash. That is how files stored before SameHashSameFile or SHA256 was turned on are brought up to date.
• The old copies are left where they are. Older versions in a node's history still point at them. Storage › Missing and redundant files removes them; after that, those older versions can no longer give their files back.
• A file that cannot be read is reported and its value is left as it was. Running the rewrite again picks up whatever is left, including the rest of a cancelled run.

From code, call DataStoreLocal.RewriteFilesAsync(toStoreId, onProgress, cancellationToken) for what the dialog does, or RewriteFilesAsync(fromStoreId, toStoreId, …) to move every file of one store into another regardless of where its property uploads. Guid.Empty names the implicit store. Both return a RewriteFilesResult with the counts and the values that could not be rewritten. DataStoreLocal.SetFileStoreWriteOptions(storeId, sameHashSameFile, hashAlgorithm) changes how an open MultiFile store writes new files; the settings are what it opens with next time.

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
}