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 shows how to shape your data, write it and get it back out, and covers the tools and services around the engine. It uses one running example domain, a venue-and-events platform, so each concept builds on the last.

Relatude.DB is pre-1.0, so the API may still change. The source is at github.com/Relatude/Relatude.DB.

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. No attribute is needed: every type in a namespace you register becomes a node type unless it is marked [Exclude]. [Node] only tunes a type (see stable type ids below), so most types in this manual do without it.

Interfaces are the recommended default, and this manual uses them almost everywhere. An interface on its own is a complete node type. db.Create<IVenue>() returns a generated proxy that implements it, tracks your changes and loads relations lazily. You never write a class.

Interfaces also give you multiple inheritance: every interface a node type implements becomes a parent node type, and a C# type can implement many interfaces but inherit only one class. §2 shows how to use this.

2. Your first node type#

The namespaces a model file usually imports:

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

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

namespace VenueApp.Models;

public interface IOrganizer : IName {   // IName gives it its Name
    Guid Id { get; set; }

    [StringProperty(UniqueValues = true, MaxLength = 254)]
    string ContactEmail { get; set; }

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

    [CreatedUtcProperty]
    DateTime CreatedUtc { get; }    // filled in by the store

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

Create, store and query it:

var org = db.Create<IOrganizer>();      // a generated proxy that implements IOrganizer
org.Name = "Nordic Live AS";
org.Slug = "nordic-live";               // required: the pattern does not match an empty value
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 get-only, and so are relation, reference and embedded properties and the marker members ([CreatedUtcProperty], [AddressProperty] and the like, §4). The store provides them, and you never assign them. Scalar properties are { get; set; }.
2. Leave Id as Guid.Empty and the store assigns one on insert, or set it yourself first.
3. Put attributes on the interface. A property is defined by the type that first declares it, so attributes on a class member that implements it are ignored. The one exception is [PropertyOverride] (§3.1).

Name comes from IName, the engine's interface for a node's name. The admin UI, GraphQL and facets show a node by it, and the datamodel must hold IName (Node names).

[Exclude] leaves a type or a property out of the datamodel.

Why interfaces are the better default#

An interface model is shorter, has no initialisation to forget and, most important, composes.

Multiple inheritance with interfaces#

The engine records every interface a type implements as a parent node type. So you can 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 : IName {
    Guid Id { get; set; }
    NodeMeta Meta { get; }

    [AddressProperty]
    string Slug { get; }          // the node's address, set with db.UpdateAddress
}

// A thing with a searchable rich-text body.
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 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 once, with their indexing and validation, and every type that implements the facet gets them. A new type that belongs on the map needs one more interface and nothing else. With classes, Venue could inherit only one base class, so you would copy properties between types and keep their attributes in sync by hand.

Querying across the hierarchy#

Query<T>() matches T and every type that inherits from it. So you can query a facet interface directly and get mixed results:

var oslo = new GeoCoordinate(59.9139, 10.7522);

// Every locatable node 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.Name}",
        IAttendee a => $"Attendee: {a.Name}",
        _           => "Something else"
    });
}

// One search box over everything that has a name
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 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 site-wide search, a "recently changed" feed or a map of everything with coordinates is then one indexed query, not one query per type merged in memory.

The example model in §11 declares every property directly on each type, so that each type reads on its own. §11.1 shows the same model built from facet interfaces. That is the shape to use in a real project.

Two constraints to design around#

The model builder refuses anything ambiguous. It checks these two rules when it builds the model, so you find out at startup:

1. Two parent interfaces may not declare the same property name. If ILocatable and ITagged both declared CountryCode, any type implementing both would fail to build. Keep facets disjoint, or move the shared member into a base interface that both extend.
2. A property cannot be declared again further down. It is defined once, on the type that first declares it. To change some of its attributes for a derived type, use [PropertyOverride] (§3.1).

When you do want a class#

Classes are fully supported. Reach for one when you want to create nodes with new without a store (seed data, tests, an import job), want behaviour on the type, or deserialise straight into it from an external feed. A class can also implement an interface: the interface is the queryable contract, and the class a form you can create. A class has four extra obligations:

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

    // The attributes are on IOrganizer and IName: 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;   // get and set on a class
}

1. A parameterless constructor is required. 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 has a setter. Still never build one: start with NodeMeta.Empty.
4. Attributes go on the interface when the class implements one.

Records and structs work too. A record needs the record Foo() { … } form to have a parameterless constructor. Structs are supported but rarely worth it.

Optional: stable type ids#

Without an id, the engine derives one from the type's full name. Renaming the type or moving it to another namespace then gives it a new identity, and the engine sees a new type with no data. Pin [Node(Id = …)] once, at the start of the project, and the type can be renamed and moved safely. The same goes for [Relation(Id = …)].

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

A property's id is derived from its declaring type's id and its own name, so a pinned type id keeps the property ids too. To rename a property, pin its id with the Id of its attribute. When the values are to be read as another property, one the type declares or inherits, name the old id with [FormerProperty] on the type (Node names shows it).

BoolValue has three values: Default (take it from the base types, else the database default), True and False. TextIndex, SemanticIndex and InstantTextIndexing are inherited by derived types (§3.1). MinNoInstances and MaxNoInstances limit how many nodes of the type may exist (see Validation happens on write).

Optional: an icon for the type#

[Node(Icon = …)] sets the icon a type is shown with, in the admin UI and in applications built on the model, such as a CMS. Use a name from the icon library the server carries, written set:name, or the source of an SVG image:

[Node(Icon = "lucide:calendar")]            // monochrome: drawn in the colour of the text around it
public interface IEvent { /* ... */ }

[Node(Icon = "fluent-color:building-24")]   // in colour
public interface IVenue { /* ... */ }

A type without an icon shows the icon of the closest type it inherits from that has one. The library holds about 22,000 icons from seven open sets, named as Iconify names them: lucide, tabler and mdi in monochrome, and fluent-color, flat-color-icons, icon-park and fluent-emoji-flat in colour. The datamodel editor's Icon field has a picker over them and also takes pasted SVG. For a type from compiled code, the editor saves the icon as an override (§3.1).

An application that shows types gets the SVG of either kind from IconLibrary.ToSvg(icon) (namespace Relatude.DB.NodeServer.Icons). It refuses SVG that could run script, so what it returns is safe to show. An icon only changes how a type is shown: changing it rebuilds no state and no index.

Optional: a title and a description#

[Node(Title = …, Description = …)] says what people call the type and what it is for. Applications built on the model show them: the Relatude CMS, for example, when an editor chooses what kind of content to create.

[Node(Title = "Article", Description = "A story with a picture, an intro and a body.")]
public interface IArticle : INamedNode, IDescribed { /* ... */ }

Both belong to the type alone and are not inherited. Without a title, an application makes one from the type name (IArticlePage reads "Article page"). Like an icon, these only change how a type is shown, and the datamodel editor saves them as overrides on a type from compiled code.

Optional: abstract types and inner node types#

Two switches say what nodes may be made of a type. Abstract = true says no node is ever of the type itself, only of the types inheriting from it: a base that gathers what they share, as an abstract class does in C#. InnerNode = true says a node of the type only lives inside another node, in one of its embedded properties (Embedded<T>): a block of a page, a line of a specification.

[Node(Abstract = true)]
public interface IPage : INamedNode { string MetaTitle { get; set; } }   // pages are articles or sections

[Node]
public interface IArticle : IPage { Embedded<Block> Blocks { get; } }

public abstract class Block { public Guid Id { get; set; } }             // abstract without saying so

[Node(InnerNode = true)]
public class TextBlock : Block { public string Text { get; set; } = ""; }

The store refuses what they rule out where a node is made: inserting a node of an abstract type, on its own or as a new inner node of an embedded property; inserting a node of an inner node type on its own; and changing a node to either kind of type. An insert fails with a NodeTypeConstraintException, a new inner node of an abstract type with a ValueConstraintException. Nodes stored before a type was marked stay as they are and can still be updated, inner nodes included. An abstract class is abstract without the attribute, and needs no public constructor, as no node is ever made of it.

Both belong to the type alone and are not inherited: a type inheriting from an abstract one is concrete unless it says otherwise, and each inner node type says so itself. The admin UI's query page and GraphQL leave inner node types out, as they cannot be queried on their own; GraphQL has no create mutation for an abstract type. Applications built on the model never offer to create a node of an abstract type, and offer an inner node type only inside an embedded property. Neither changes how nodes are stored, so changing either rebuilds no state and no index, and the datamodel editor can set them as overrides on a type from compiled code (IsAbstract, IsInnerNode).

3. Scalar properties and their attributes#

A property needs no attribute: the engine infers a sensible property model from its CLR type. Add an attribute when you want indexing, validation, faceting or search.

The most important flag is Indexed. A property must be indexed to be filtered and sorted efficiently, and to be a facet. Without an index, the engine scans.

The attribute catalogue#

All of them inherit these options from PropertyAttribute:

public abstract class PropertyAttribute : Attribute {
    public string? Id { get; set; }              // a pinned property id, so it can be renamed
    public string? ReadAccess { get; set; }      // the user group that may read the value
    public string? WriteAccess { get; set; }     // the user group that may write it
    public bool ExcludeFromTextIndex { get; set; }
    public int TextIndexBoost { get; set; }      // extra times the value goes into the text index
    public TitleLayout TitleLayout { get; set; } // where an editor puts the title: Default, Left, Above or None
    public string? Unit { get; set; }            // shown by an editor right of the control: "kg"
    public string? Height { get; set; }          // how tall an editor makes the control: "300px", "50%"
    public string? Width { get; set; }           // how wide an editor makes the field: "50%", "300px"
    public string? Title { get; set; }           // what an editor labels the field: "Main picture"
}

TitleLayout, Unit, Height, Width and Title only say how an editing interface, such as the Relatude CMS, shows the property. TitleLayout puts its title to the Left of the control on one line, Above it, or None (the control alone). Default, which is also what you get when you leave it out, lets the editor choose what suits the control: the CMS puts the title above a text area, a code editor, an HTML field, embedded nodes and a list of related or referenced nodes, and to the left of any other control, a single related or referenced node among them. Unit is shown to the right of the control. Height is a CSS length for a control that has a height to give, such as a text area or an HTML field; the CMS reads a number alone as pixels and a percentage as a share of the height its form has in view. Width is how wide the field is: a percentage is a share of the form's row, which fields share while they fit, so two fields of 50% sit side by side; a CSS length such as 300px is a field of that width, at most the row's. Left out, the field takes the whole row. Title is the label; left out, the editor makes one from the member's name. Each may be left empty. The store ignores them all, so changing them rebuilds nothing. Read them from PropertyModel.TitleLayout (null for Default), PropertyModel.Unit, PropertyModel.Height, PropertyModel.Width and PropertyModel.Title.

using Relatude.DB.Datamodels.Properties;   // TitleLayout

[DecimalProperty(TitleLayout = TitleLayout.Left, Unit = "kg")]
decimal Weight { get; set; }

[HtmlProperty(Height = "400px")]
string Body { get; set; }

[StringProperty(Title = "First name", Width = "50%")]
string FirstName { get; set; }

[StringProperty(Title = "Last name", Width = "50%")]
string LastName { get; set; }

Strings#

[StringProperty] has the most options. Here they all are on one property:

[StringProperty(
    Indexed = true,                       // value index: equality, ranges, sorting, facets
    IndexedByWords = true,                // full-text (BM25) index
    IndexedBySemantic = true,             // vector index for semantic search
    PrefixSearch = true,                  // "starts with" search in the word index
    InfixSearch = false,                  // "contains" search in the word index; costs space
    MinWordLength = 3, MaxWordLength = 30,  // words outside these lengths are not indexed
    MinLength = 0, MaxLength = 4000,
    Trim = true,                          // strip white space at both ends, before the rules
    CaseTransform = CaseTransform.ToLowerCase, // or NoTransform, ToUpperCase; after Trim
    LegalCharacters = "abcdefghijklmnopqrstuvwxyz0123456789-",
    RegularExpression = @"^[a-z0-9-]+$",
    RegularExpressionMessage = "Use lower case letters, digits and dashes",
    UniqueValues = true,
    CaseSensitive = false,                // the default: "Ole" and "ole" clash under UniqueValues
    IgnoreDuplicateEmptyValues = true,    // many nodes may be empty under UniqueValues
    NotFacet = false,                     // true keeps an indexed property out of facets
    DefaultValue = ""
)]
public string Slug { get; set; } = string.Empty;

LegalValues = new[] { "draft", "published" } limits the value to a list. StringType says what the text is: AnyString (the default), SingleLineText, MultiLineText, Code, HTML, Markdown, JSON, JavaScript, TypeScript, CSharp or CSS. StringValueType and CaseTransform are in Relatude.DB.Datamodels.Properties.

SingleLineText and MultiLineText are plain text that an editing interface shows as a text box or as a text area. Code is source code in any language, shown in a code editor; JSON, JavaScript, TypeScript, CSharp and CSS are code in one language. With AnyString the editor chooses; the CMS goes by the property's name. The store keeps and indexes AnyString, SingleLineText, MultiLineText and Code the same way, so moving between them rebuilds nothing. The datamodel editor shows StringType as Content, right under the property's name. TextLines says how many lines a text area or a code editor shows:

[StringProperty(StringType = StringValueType.SingleLineText)]
public string Headline { get; set; } = string.Empty;

[StringProperty(StringType = StringValueType.MultiLineText, TextLines = 6)]
public string Summary { get; set; } = string.Empty;

[StringProperty(StringType = StringValueType.Code, TextLines = 8)]
public string Sample { get; set; } = string.Empty;

public string Language { get; set; } = "csharp";   // the CMS highlights Sample in this language

Use [HtmlProperty] for rich text. It sets StringType = HTML, so links to nodes and files inside the value keep working when their targets move (§18.2):

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

Numbers#

Numeric attributes share MinValue, MaxValue, DefaultValue, Indexed and NotFacet. FacetRangePowerBase and FacetRangeCount control how the engine splits the values into buckets when you ask for a range facet:

[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; }

decimal, DateTime, DateTimeOffset, TimeSpan and Guid cannot be C# attribute arguments, so their bounds and defaults are 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; }

Ids of node types, properties and relations#

A Guid or Guid[] property can hold ids from the datamodel itself. GuidType says what kind of id it holds, so an editing interface such as the CMS can offer them by name in a drop-down instead of as Guids:

[GuidArrayProperty(GuidType = GuidValueType.NodeType)]
public Guid[] NodeTypes { get; set; } = [];

[GuidProperty(GuidType = GuidValueType.Property)]
public Guid SortBy { get; set; }

[GuidProperty(GuidType = GuidValueType.Relation)]
public Guid Tree { get; set; }

GuidValueType is in Relatude.DB.Datamodels.Properties. The default, AnyGuid, means any id. The store does not check the ids or follow them, so an id can still name a type after that type has been removed. The datamodel editor shows GuidType as Id of, under the property's name.

Enums#

Declare the property as your enum type. The engine stores it as an integer and fills in the enum's names (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 gets the same names:

public enum AccessibilityFeature { StepFree, HearingLoop, AccessibleToilet }

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

Validation happens on write#

The engine checks LegalValues, LegalCharacters, RegularExpression, MinValue/MaxValue, MinLength/MaxLength, UniqueValues and MinNoInstances/MaxNoInstances every time a node is written. A write that breaks a rule fails, and its whole transaction is rolled back. Stored values are not checked again. If you tighten a rule, the database still opens, but a node that breaks the new rule cannot be saved until its value is fixed.

A refused value throws a ValueConstraintException. Its PropertyId names the property, and its message is written for the person who typed the value, for example PostCode "12" is not valid: Enter four digits.

• Trim and CaseTransform change the value first: white space is removed from both ends, then the case is changed (invariant culture). The rules check the changed value, and the changed value is stored. So with CaseTransform = ToLowerCase, a unique email is unique however it is typed. Queries are not transformed: a query for "Ole@Example.com" on a lower-cased property finds nothing.
• RegularExpression must match every value written, the empty value too. A pattern like ^[a-z0-9-]+$ therefore makes the value required. For an optional value, allow empty in the pattern: ^([a-z0-9-]+)?$. Without ^ and $, the pattern may match anywhere in the value. Set RegularExpressionMessage to say what a valid value looks like; without it, the message shows the pattern.
• LegalCharacters lists the characters a value may contain. The empty value is always allowed.
• UniqueValues on a string ignores case unless you set CaseSensitive = true. By default, no node can have "OLE" when another has "Ole". Only the check ignores case: the value is stored, sorted and queried as written.
• LegalValues on a string is compared ordinally. The empty value is always allowed, so add MinLength = 1 to require a value.
• LegalValues on an integer limits a plain int to the listed values. An enum property is not limited to its members: a [Flags] combination, or a member a newer version of your code adds, is accepted.
• MinNoInstances / MaxNoInstances on [Node] count the nodes of the type and of every type that inherits from it, including nodes that are unpublished, hidden or marked as deleted. The check is on what the whole transaction leaves, so deleting a node and inserting its replacement passes at the limit. A transaction that adds nodes is refused above the maximum, and one that removes nodes below the minimum, with a NodeTypeConstraintException. So with MinNoInstances = 1 you can always insert the first node, but never delete the last.

3.1 Overriding attributes#

An override changes an attribute without editing its declaration. Use one when the type comes from an assembly you do not build, when the property is declared on a base type that other types share, or when one installation needs another value without a rebuild. Three layers decide what a type ends up with, and a later layer wins:

1. Declared: the attributes on the type or the property, as described above.
2. Overridden in code: a derived type sets its own value for a switch or a property attribute it inherits.
3. Overridden in the database: values set in the admin UI's datamodel editor, or by hand in JSON. They are applied when the database opens, as if the source said so.

Text index switches are inherited. TextIndex, SemanticIndex and InstantTextIndexing on [Node] apply to the type they are set on and to the types that inherit from it. A type that does not set one takes it from its closest base type that does, and then from the database default (EnableTextIndexByDefault and friends, §12.1).

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

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

If two unrelated base types disagree, the type gets the database default, and the database logs a warning naming both. Set the switch on the type itself to choose. Semantic indexing needs the text index, so a type that is semantically indexed stays text indexed whatever its TextIndex says.

Inherited properties: [PropertyOverride]. A derived type can set five things for a property it inherits:

Anything you leave out comes from the base types. In this example, news articles get their own defaults and an index on Status, and support tickets keep their body out of search:

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

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

[PropertyOverride(nameof(IContent.Title), DefaultValue = "Untitled news", TextIndexBoost = 2)]
[PropertyOverride(nameof(IContent.Status), DefaultValue = ContentStatus.Published, Indexed = BoolValue.True)]
public class NewsArticle : IContent { /* ... */ }

// The body holds customer details, so it stays out of search.
[PropertyOverride(nameof(IContent.Body), ExcludeFromTextIndex = BoolValue.True)]
public class SupportTicket : IContent { /* ... */ }

db.Create<NewsArticle>() starts with the title "Untitled news" and the status Published. Other IContent types keep "Untitled" and Draft. A news title goes into the text index two extra times, so it weighs more in search. new NewsArticle() is plain C#, so it starts with the property initialisers instead.

A few more rules:

• On a member. A class member that implements an interface property can carry the attribute without the name: [PropertyOverride(TextIndexBoost = 2)] public string Title { get; set; }. It is the only property attribute such a member can carry.
• Down a class chain. An override reaches every type that inherits from the type it is set on, and a more specific type can override it again. Interfaces can carry overrides too.
• Decimals, dates, durations and guids are strings, in the formats of the property attributes (Numbers), for example DefaultValue = "25". An enum default is the enum value.
• Unrelated base types that disagree cancel out: the type gets what the declaration says, and the database logs a warning.

The index and the facet are shared. A property has one value index and one set of facet counts, whichever types have it. Indexed = BoolValue.True on NewsArticle gives the property its index, and that index holds the status of every IContent node, not only of news articles. A property is indexed when its declaration says so or any type asks. BoolValue.False only takes back a type's own request: to drop an index that the declaration has, override Indexed on the declaring type. Facets work the same way. A facet counts the values in the value index, so it needs an index: ask for both when the base type has neither. Everything else about a property, such as its other index settings and its rules, is one setting wherever the property is used.

Mistakes stop the build. A [PropertyOverride] that cannot apply fails the model build at startup, with a message naming the type and the property. It fails when the attribute:

• names a property the type declares itself (set that property's own attribute instead);
• names no member of the type (use nameof to avoid typos), or a member marked [Exclude];
• names a system member: the id, NodeMeta, the created or changed date, or the address marker;
• gives a DefaultValue that does not convert to the property's type, or gives a default to a property that has none (arrays, files, references and the like);
• sits on a type without naming a property, or sits on a member and names another property;
• names a property that another [PropertyOverride] on the same type also names. Combine them.

What can be overridden. In code, [PropertyOverride] takes the five attributes above. In the database you can override these:

What the compiled code depends on cannot be overridden: ids and names, the property type, what a type inherits, the shape of a member (ReferenceValueType, RelationValueType, EmbeddedValueType), the relation a property is an end of, the types a reference or an embedded property points at, an embedded map's key, and enum metadata. CultureSpecific cannot be overridden either. A rule such as UniqueValues is checked as values are written; values already stored are left as they are. [Node] also has a TextIndexBoost, which the engine does not use yet.

In the database: the datamodel editor. The admin UI's Models page writes a change into the source that defines the type when it can. Where it cannot, as for compiled classes or types added in OnDatamodelInit, it saves what you set as an override. Each field shows where its value comes from, and you can remove an override there. Activating saves the overrides and reopens the database.

A database keeps its overrides in two files, the same way it keeps its settings in relatude.db.json and relatude.db.overrides.json (§12):

When the database opens, THIS SERVER is merged over SHARED. A value in THIS SERVER replaces the SHARED value, and null removes it, so the attribute follows the source again on this installation. Activating writes only the THIS SERVER file, and only what differs from SHARED. Both files are keyed by ids, with names beside them for people to read:

// relatude.data/overrides/datamodel.overrides.json (THIS SERVER)
{
  "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. Move to shared, at the top right of the editor, moves the overrides you select from THIS SERVER into SHARED, as on the settings pages. Do it in the Development environment, where relatude.settings is the folder in your project, and commit the file. On a deployed server the next deployment would replace it. The SHARED file is found by the database's short name, so set the short name in relatude.db.json.

An override in the database that cannot apply is skipped with a warning in the log and the editor: its type or property is gone, its value does not parse, or the attribute cannot be overridden. It never stops the database from opening. From code, set Datamodel.Overrides before the store is created.

Before you change a value on a running installation:

• A default is late bound. A node with no stored value reads the current default, so a new default reaches nodes that never had a value. Stored values are never touched. If the property is indexed, queries 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 stored values.
• Index changes rebuild. Turning on Indexed or IndexedByWords, or asking for an index from a derived type, changes the model. The database then rebuilds its state and indexes from the log at the next open. When text indexing changes for a type, its nodes are queued for text indexing. Settings that only change how a type is shown (Icon, Title, Description, Display, TitleLayout, Unit, Height, TextLines, GuidType) rebuild nothing.

Passwords#

A PasswordValue property holds a password. By default the store keeps it as an Argon2id hash, which can be verified but never read back. A property can also allow a password encrypted with the database's key (AES-256-GCM), which can be read back, or kept as plain text. The code chooses how to keep a password when it sets one:

public class Member {
    public Guid Id { get; set; }
    public string Email { get; set; } = "";

    [PasswordProperty(MinLength = 10, RequireDigit = true)]
    public PasswordValue Password { get; set; } = PasswordValue.Empty;

    [PasswordProperty(AllowEncrypted = true, AllowHashed = false)]
    public PasswordValue SmtpPassword { get; set; } = PasswordValue.Empty;
}

member.Password.SetPassword("correct horse battery 7");           // hashed, the default
member.SmtpPassword.SetPassword(secret, PasswordStorage.Encrypted);
db.Update(member);                                                  // hashed and encrypted here

var m = db.Get<Member>(id);
m.Password.IsSet;                   // true
m.Password.Storage;                 // PasswordStorage.Hashed
m.Password.Verify(typed);           // true or false
m.Password.IsPasswordRetrievable;   // false: a hash cannot be read back
m.SmtpPassword.GetPassword();       // the password, decrypted with the database's key
m.Password.Clear();                 // removed when the node is next written

PasswordValue and PasswordStorage are in Relatude.DB.Common. What to know:

• The store does the work on write. SetPassword and Clear only record the change. When the node is written, the store checks the property's rules and makes the hash or the encryption. A refused password fails the write with a ValueConstraintException that never quotes the password.
• The password never leaves the store. Only the stored form reaches the log. JSON gives {"isSet": true, "storage": "Hashed"}; send {"set": "...", "storage": "Hashed"} or {"clear": true} to change it. A value that holds no change, like a stale object saved again, leaves the stored password as it is.
• A query can only ask IsSet: Where(m => m.Password.IsSet). Comparing, sorting, grouping or selecting a password throws. A password is never in an index, the text index, GraphQL or a facet.
• NeedsRehash is true when a password was kept with other hash settings, pepper or key than the store's current ones. Set the password again after a successful Verify at sign-in.

The keys are database settings, under LocalSettings.Passwords in relatude.db.json (the Passwords group on the admin UI's Content settings page):

"Passwords": {
  "EncryptionKey": "<32 random bytes in base64>",
  "OldEncryptionKeys": [ "<a previous key, still used to decrypt>" ],
  "Pepper": null,
  "HashMemoryKiB": 19456, "HashIterations": 2, "HashParallelism": 1
}

Keep the keys in configuration or user secrets, which the server never writes to its settings files. Without EncryptionKey, no password can be kept encrypted. Losing it loses every encrypted password, so keep a copy, and when you change it, move the old key into OldEncryptionKeys. The Pepper is an optional secret mixed into every hash. Set it once, before the first password: a hash made with another pepper cannot be verified. The hash settings default to OWASP's minimum for Argon2id, and each hash keeps the settings it was made with.

The property's options, in the attribute and the datamodel editor: AllowHashed (on), AllowEncrypted and AllowPlainText (off), MinLength (8), MaxLength (128), RequireUppercase, RequireLowercase, RequireDigit, RequireSymbol, and RegularExpression with RegularExpressionMessage. A password property cannot be indexed, unique or per culture, or sit on a type kept inside another node's embedded property. A remote store cannot set a password: only the store that keeps the node has the keys.

4. Marker properties#

A marker attribute maps a member to a value the store keeps for every node. The member is not a property of its own: the store fills it in when it reads the node, and other attributes on it are ignored. Use each marker at most once per type.

public interface IArticle : IName {                  // Name: the node's name (below)
    Guid Id { get; set; }

    [AddressProperty]    string Address { get; }
    [CreatedUtcProperty] DateTime CreatedUtc { get; }
    [ChangedUtcProperty] DateTime ChangedUtc { get; }
}

• On an interface, declare marker members getter-only. The store writes these values, not your code, and a { get; set; } marker member stops the store from starting.
• Set the address with UpdateAddress, in the same transaction as the insert if you like. On a class, you can also set an [AddressProperty] member before you save.
• The name is not a marker. It is the ordinary property IName.Name, which you set, index and query like any other (Node names).

Inserting a node together with its address:

var article = db.Create<IArticle>();
article.Name = "Winter Session";

db.CreateTransaction()
  .Insert(article)
  .UpdateAddress(article, "winter-session")
  .Execute();

Node names: IName#

A node's name is one property, IName.Name, in the engine's own model (namespace Relatude.DB.Native.Models). A type has a name when it inherits IName. An interface inherits the property and declares nothing more; a class implements it with a plain Name, with no attribute of its own:

using Relatude.DB.Native.Models;   // IName

public interface IVenue : IName {
    Guid Id { get; set; }
    // ...
}

public class Brand : IName {
    public Guid Id { get; set; }
    public string Name { get; set; } = "";
}

IName.Name is a string with a value index ([StringProperty(Indexed = true)]), and its id is NodeConstants.NamePropertyId. It has no word index of its own, so MatchesSearch does not apply to it; WhereSearch finds names through the node's text index (§21). Every named type shares that one property, so one index holds the names of all of them. A query over IName sorts and filters nodes of every named type by name:

var all  = db.Query<IName>().OrderBy(n => n.Name).Page(0, 50).Execute();   // every named type, A to Z
var oslo = db.Query<IName>().Where(n => n.Name == "Oslo").Execute();

The datamodel must hold IName, as it holds every type a node type inherits. Add it with dm.Add<IName>(), or the engine's whole model with dm.AddNamespace<ISystemUser>() (§12).

Nothing else is a name, and nothing is guessed from other properties. A node of a type without IName, or with an empty Name, has no name. What uses the name:

• The admin UI shows a node by its name, else its address, else its id. A type's table puts Name first.
• GraphQL has it as the system field name on every node type (§33.3).
• Facets on a relation or a reference label each bucket with the related node's name (§28).
• The text index of a node takes in its related nodes' names with [RelationProperty(TextIndexRelatedName = true)] (Relation options).

Code that works with a node's raw data (INodeData) gets the name with NodeName.Of(node) (namespace Relatude.DB.Datamodels): the name, or null when the type has none or it is empty. NodeTypeModel.HasName says whether a type has a name.

Names stored under another property. A type that moves from a Name or Title of its own to IName keeps its stored names with [FormerProperty(id, property)]. On a node type, it reads the values its nodes stored under a property the type no longer has, the one with that id, as the property named: one of the type's own or one it inherits.

[Node]
[FormerProperty("42c0ded9-2148-eff3-b91f-d686f8b2b3da", nameof(IName.Name))] // its own Name, stored before
public class Brand : IName {
    public Guid Id { get; set; }
    public string Name { get; set; } = "";
}

• The id is the old property's: the one pinned with Id =, or the one derived from its type's id and member name. The datamodel JSON in the database's datamodels folder shows it.
• A node that also holds a value under the new property keeps that one.
• A node read holds the value under the new property, and stores it there when it is next written. The indexes are rebuilt once at the next open, as for any change to the model.
• Types inheriting the type read their nodes the same way. A type may carry several [FormerProperty] attributes, one per old id (NodeTypeModel.FormerPropertyIds).

The datamodel editor warns (own-name) about a type that has a property of its own called Name, which is not the node's name, and suggests IName with [FormerProperty].

What lives in NodeMeta#

Every node carries system data, which a NodeMeta Meta { get; } member reads. Never create or assign a NodeMeta yourself. Change the writable fields with UpdateMeta (Writing meta), and the address with UpdateAddress.

ChangedUtc moves with every write that changes the node's values. A meta write, or a write that changes nothing, leaves it alone. An insert keeps a change time it is given, as an import needs.

ChangedBy is stamped with it: the user of the context the write runs in (db.Context.User(id)), Guid.Empty for a context with no user, and NodeConstants.MasterAdminUserId for Admin(). An insert sets CreatedBy too, and so does a new revision. Publishing a revision or moving it to another culture also names its writer. An insert keeps writers it is given. The log keeps every version with its meta, so FindOlderVersions tells who wrote each one.

Writing meta: UpdateMeta#

UpdateMeta writes meta fields by name: one name and value, or several pairs in one write. The names are the property names of IInnerNodeMeta, so write them with nameof. Each value must have the field's own type (Guid, bool, DateTime?): it is cast, not converted.

using Relatude.DB.Datamodels;   // IInnerNodeMeta, NodeConstants

// one value: only the members' group can read the article
db.UpdateMeta(article.Id, nameof(IInnerNodeMeta.ReadAccess), membersGroup.Id);

// several at once
db.UpdateMeta(article.Id, [
    new(nameof(IInnerNodeMeta.EditAccess), NodeConstants.UserGroupAdmins),
    new(nameof(IInnerNodeMeta.ReleaseUtc), (DateTime?)new DateTime(2027, 3, 1, 9, 0, 0, DateTimeKind.Utc)),
    new(nameof(IInnerNodeMeta.ExpireUtc), null!),   // no expiry
]);

// together with other writes, in one transaction
db.CreateTransaction()
  .Update(article)
  .UpdateMeta(article.Id, nameof(IInnerNodeMeta.ReadAccess), NodeConstants.UserGroupEveryone)
  .Execute();

CultureId and the revision type cannot be written this way, and neither can an unknown name: the call throws. The revision methods change culture and type (§29).

On a node with revisions, a revisionId argument writes that revision's meta. The access groups, the collection and the deleted flag are copied to the other revisions. Without a revisionId, every revision is written. All overloads also take the internal int id, and Transaction has the same methods.

Querying by the node's own dates#

CreatedUtc and ChangedUtc are indexed for every node of every type. Query them through NodeMeta, whether or not the type maps them to members:

// recently changed articles
db.Query<IArticle>().OrderByMetaDescending(m => m.ChangedUtc).Page(0, 50).Execute();
db.Query<IArticle>().WhereMeta(m => m.CreatedUtc >= since).Count();

A [CreatedUtcProperty] or [ChangedUtcProperty] member answers the same queries from the same index: OrderByDescending(x => x.ChangedUtc). In a query string the two are n._createdUtc and n._changedUtc. No other NodeMeta field can be queried.

5. Geo coordinates#

GeoCoordinate (in Relatude.DB.Common) is a WGS84 latitude and longitude. It is a small readonly struct, and an indexed GeoCoordinate property answers radius queries from a spatial index.

using Relatude.DB.Common;

public interface IVenue {
    // ...
    [GeoCoordinateProperty(Indexed = true)]     // index it for radius queries
    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);

The empty value#

GeoCoordinate.Empty, the default value, 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 left out of the spatial index. A venue without a location never shows up in a "within 5 km" search.

Distance and radius tests#

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

Inside a query, IsWithin(center, meters) uses the spatial index (§22).

Precision and sort order#

A coordinate snaps to a grid of about 1 cm when you construct it, so a stored value reads back equal to what you wrote. Values sort along a Z-order curve. That keeps index scans fast but means nothing to a reader, so never OrderBy(v => v.Location). To sort by distance, see §22.

JSON shape#

GeoCoordinate serialises as {"latitude": 59.91, "longitude": 10.75}, and Empty as null. When reading, it also accepts lat, lon and lng, and a "latitude, longitude" string.

Seeing them#

The admin UI's query page has a Map view. It draws a GeoCoordinate property of the current result on a map or a globe, as pins, a heat map, clusters or shaded countries. Nodes without a location are left out. An indexed property is read from the index, so even large results draw fast.

6. Files#

FileValue (in Relatude.DB.Common) refers to a file in the store's file storage: local disk, Azure blob storage and others, configured separately. The node holds the reference, and the bytes live in the storage.

[FileProperty]
FileValue Photo { get; set; }

// keep this property's files in one particular file store:
[FileProperty(FileStorageProviderId = "b1c2d3e4-...")]
FileValue Brochure { get; set; }

FileStorageProviderId is the id of a file store from the settings (§12.1). Uploading and serving files is covered in §17, and the URLs they are served on in §18.

6.1 File analysis#

The database can learn what is in the files you upload, in the background after each upload, using the Image AI and File to text services (§34). Four database settings turn it on for every file property, all off by default:

They are under Settings › Search & AI › File analysis in the admin UI, or in LocalSettings (§12.1). A file property can decide for itself. BoolValue.Default follows the database setting:

[FileProperty(ImageMetaAnalysis = BoolValue.True)]        // always analysed, whatever the default
FileValue Photo { get; set; }

[FileProperty(FileTextIndexing = BoolValue.False)]        // never read, even with the default on
FileValue SignedContract { get; set; }

[FileProperty(VideoAndAudioFileTextIndexing = BoolValue.True)]
FileValue Recording { get; set; }

The crop mode analysis asks Image AI whether the picture is a graphic (a logo, an icon, an illustration, a diagram, a chart, a map, a screenshot, a page of text, or a product alone on a plain ground) or a photograph. When it is at least 70 sure in 100, the picture's CropMode becomes Fit for a graphic, shown whole, or Fill for a photograph, cropped about its focus point. A picture left at Fit, Auto or no crop mode also gets a BackgroundColor: the commonest colour along its sides, else their average, so the room around it looks like more of it. Edges that are mostly see-through leave the background as it was. An SVG has no crop mode analysis.

What happens. An upload or a file copy queues a background task (Settings › Tasks shows it). The task sends the file to the service, then writes the result into the file value: the text goes into TextExtract, and everything else goes into MetaJSON as typed meta. That write queues the node for text indexing again, so the words, the title, the description and the keywords make the node findable with WhereSearch (§21). For recordings, the search text has the timestamps removed.

Each file analysed is charged to the license. A file is analysed once. Two kinds of failure are treated differently:

• The service refuses the file (a kind it does not read, or a file that is too large). This is recorded in the meta, and the file is not sent again.
• The call fails (no credits, no answer). Nothing is recorded, and the file is tried again at the next text reindex.

The background task fills in only what is not set: a title, a description, keywords, a focus point, a crop mode or a background set by a person stays.

Analysing at once. db.Datastore.AnalyseFileAsync(propertyPath, kinds, force, ctx) runs the analyses now, in the version the context reads, and keeps each result as it is done. It answers the file and a report per kind (done, done before, skipped, not possible here, failed). Without force, analyses done before are not done again. With force they are, and the results replace what was set by hand. The same analysis of a file is never run twice at once: a second request, such as the background task's, waits for the first. GetFileAnalyses(propertyPath, value) tells which analyses the property wants, which are done, and which the database can do here.

var path = new PropertyPath(productId, pictureProperty.Id);
var report = await db.Datastore.AnalyseFileAsync(path, FileAnalysisKinds.ImageMeta | FileAnalysisKinds.ImageCropMode, force: true);
foreach (var step in report.Steps) Console.WriteLine(step.Kind + ": " + step.State + ", " + step.Summary);

Files uploaded before a switch was on are analysed when the text index is rebuilt: Storage › Maintenance › Rebuild text index in the admin UI, db.Datastore.ReIndexAllText(), or the reindex-text job (§36). The rebuild queues every stored file that is still missing an analysis.

Reading the meta. FileValue.GetMeta() returns the meta as a class that matches the kind of file:

var photo = db.Get<Product>(id).Photo;

if (photo.TryGetMeta<ImageFileMeta>(out var image)) {
    var focus = image.FocusPoint;        // null if the service found none
    var tags = image.Keywords ?? [];
    var faces = image.Objects?.Count(o => o.Type == ImageObjectType.Face) ?? 0;
}

var meta = photo.GetMeta();              // always a FileValueMeta, of the file's own kind
bool read = meta.TextExtraction?.Succeeded == true;
string text = photo.TextExtract;         // the file's text, or a timed transcript

TextExtraction, AiAnalysis and CropModeAnalysis record when the step ran, which provider ran it, and the Error if the service refused the file. Technical holds what the decoder reported when the file was stored: the image details, or the probe of a video. You can also write the meta yourself with SetMeta(meta) and then save the node.

7. Embedded data#

Embedded objects are owned values. They are stored inside the parent node, have no identity in the graph, and are deleted with it. Use them for data that only makes sense with its parent: opening hours on a venue, line items on an order, price tiers on an event.

An embedded class is part of the model, so register it with your node types (§12): AddNamespace picks it up, Add<T> on the parent does not. On an interface, declare embedded properties getter-only; the store creates the collection. On a class, initialise them: declare an Embedded<T> getter-only, { get; } = [];, which the store fills, and an EmbeddedMap with a setter, { get; set; } = [];. There are two kinds.

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

public class PriceTier {
    public Guid Id { get; set; }
    public string Name { get; set; } = string.Empty;   // "early bird", "standard", …
    public decimal Amount { get; set; }
}

public interface IEvent {
    // ...
    [EmbeddedProperty]
    Embedded<PriceTier> PriceTiers { get; }
}

IncludeTypes says which types the collection takes. The default, ThisTypeAndDescending, takes PriceTier and its subclasses; ThisTypeOnly and DescendingTypesOnly narrow that.

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))]
    EmbeddedMap<string, OpeningHours> Hours { get; }
}

KeyProperty names the property that holds the key. It must be declared on the closest common base of the allowed value types, and its type must be TKey; the model builder checks both. To key by the value's id instead, set KeyType to KeyPropertyType.NodeGuidId or NodeIntegerId. Without an attribute, a Guid or int key means the value's id, and any other key type is an error.

Working with an embedded map#

var venue = db.Create<IVenue>();
venue.Hours.Add(new OpeningHours { DayCode = "mon", Opens = new(9, 0, 0), Closes = new(23, 0, 0) });
db.Insert(venue);

// keys work once the parent is stored
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)                   // enumerates the values
    Console.WriteLine($"{h.DayCode}: {h.Opens}–{h.Closes}");

foreach (var (day, h) in stored.Hours.KeysAndValues()) { … }   // with the keys

Keys need a stored parent. Before the parent is inserted, only Add, Clear, Count and enumeration work. Everything that uses a key (the indexer, Contains, TryGetValue, Remove, KeysAndValues()) throws InvalidOperationException, because the store evaluates the keys.

8. References — lightweight pointers#

A reference stores the id of another node on this node. It points one way: it is cheap to store and to set, and the target does not know about it.

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

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

On a class, initialise them: public Reference<IMediaAsset> Cover { get; set; } = new();.

Display and AllowInlineEditing say how an editing interface shows the nodes referred to (§10).

Reading and writing a Reference<T>#

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

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

if (ev.Cover.TryGet(out var asset))     // 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 node
ev.Cover.Clear();
db.Update(ev);                          // a reference is node data: save it with 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(organizer, db);
ev.Sponsors.Remove(organizerId);        // removes every occurrence
ev.Sponsors.Clear();
ev.Sponsors.Ids = [a, b, c];            // replace them all, in this order
db.Update(ev);

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

Get() skips stale targets, such as deleted nodes or nodes of the wrong type, instead of throwing.

foreach yields only preloaded targets. Reference<T> and References<T> are IEnumerable<T>, but a foreach over one yields nothing unless the query loaded the targets with .Preload(...) (§24). Otherwise use Get() or TryGet(out …). This is on purpose: it makes an accidental N+1 load impossible.

9. Relations — the graph edges#

A relation is an indexed edge between two nodes, readable from both ends: relating A to B also relates B to A. Relations can be traversed, filtered and counted without loading the nodes.

Relations are not foreign keys: you never store a VenueId on an event. You declare a relation class with a nested class for each end, and use the nested classes as property types.

The five shapes#

// 1. Symmetric one-to-one: twin venues. Both ends are the same property.
public class PairedWith : OneOne<IVenue> {
    public class Pair : One { }
}

// 2. Directional one-to-one: an organizer's primary contact.
public class PrimaryContact : OneToOne<IOrganizer, IAttendee> {
    public class Organizer : OneFrom { }   // on IAttendee
    public class Contact   : OneTo { }     // on IOrganizer
}

// 3. Directional one-to-many: the workhorse.
public class EventsAtVenue : OneToMany<IVenue, IEvent> {
    public class Venue  : One { }     // on IEvent: its one venue
    public class Events : Many { }    // on IVenue: its many events
}

// 4. Symmetric many-to-many: friends.
public class Friends : ManyMany<IAttendee> {
    public class Peers : Many { }
}

// 5. Directional many-to-many: events and their attendees.
public class Attendance : ManyToMany<IEvent, IAttendee> {
    public class Events    : ManyFrom { }   // on IAttendee
    public class Attendees : ManyTo { }     // on IEvent
}

There is no zero-or-one and no separate many-to-one: use OneToMany from the other end. When the edge itself carries data, such as a ticket price or a role, make the edge a node type with a relation to each side.

Using them on node types#

Each nested class is a property type. Name the property whatever reads best:

public interface IVenue {
    // ...
    EventsAtVenue.Events Events { get; }          // the venue's events
}

public interface IEvent {
    // ...
    EventsAtVenue.Venue  Venue     { get; }       // the event's venue
    Attendance.Attendees Attendees { get; }
}

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

Declare only the ends you navigate. You never assign an end: relate nodes with AddRelation, SetRelation and the other verbs in §14. On a class, initialise each end with new().

The "one" side API#

A One, OneFrom or OneTo end is a OneProperty<T>:

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

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

A foreach over a one end yields only what the query included (§24). Use Get or TryGet to load it.

The "many" side API#

A Many, ManyFrom or ManyTo end is a ManyProperty<T>:

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

int n    = venue.Events.Count();         // from the relation index: loads no nodes
bool has = venue.Events.Contains(eventId);

foreach (var e in venue.Events) { … }    // loads lazily when nothing was included
var all = venue.Events.Get();            // IEnumerable<IEvent>

// a full query rooted at the relation, for anything more
var upcoming = venue.Events
                    .Query()
                    .Where(e => e.StartsUtc > DateTime.UtcNow)
                    .OrderBy(e => e.StartsUtc)
                    .Page(0, 20)
                    .Execute();

Query() returns an IQueryOfNodes, so everything in Part III applies to it. When you loop over the ends of many parents, Include them in the query instead (§24).

9.1 Relation lists are ordered#

A many end is a list, not a set: its order is stored, and you can change it. Use it for hand-curated sequences, such as a running order, a menu or a gallery, instead of a SortIndex property.

• AddRelation appends at the bottom.
• Reads follow the stored order: foreach, Get() and included ends all return it.
• No duplicates. Relating a pair that is already related throws, and so does removing a pair that is not related.
• Each end has its own order. In a many-to-many relation, the order of attendees on an event and the order of events on an attendee are separate.

A one end holds at most one node, so ordering applies to many ends only.

The MoveRelation… family#

These methods change the order without adding or removing anything:

db.MoveRelationToTop<IVenue>(venue, v => v.Events, headliner);
db.MoveRelation<IVenue>(venue, v => v.Events, ev, offset: -1);
db.MoveRelationBefore<IVenue>(venue, v => v.Events, ev, anchor: other);
db.SetRelationOrder<IVenue>(venue, v => v.Events, orderedEvents);

// relate and position in one transaction
db.CreateTransaction()
  .AddRelation<IVenue>(venue, v => v.Events, ev)
  .MoveRelationToTop<IVenue>(venue, v => v.Events, ev)
  .Execute();

• Pass several items and they move as a block that keeps its own order.
• Positions are clamped. Moving past the top or the bottom never throws.
• SetRelationOrder must list exactly the nodes related now. It only reorders.
• Never reorder by removing and adding again. That is two writes, and the add lands at the bottom.

All of them are on NodeStore and on Transaction, where calls chain. Besides nodes and an expression, they take Guid ids or a raw property id; Transaction also takes internal int ids.

Relation options#

[Relation(
    Id = "9f4e2c11-77a3-4d5e-8b21-0c6f9a3e7d54",  // a stable id that survives renames
    DisallowCircularReferences = true              // no cycles in a relation of a type to itself
)]
public class VenueTree : OneToMany<IVenue, IVenue> {
    public class Parent   : One { }
    public class Children : Many { }
}

[Relation] also takes SourceTypes and TargetTypes, but the generic parameters already say that.

[RelationProperty] on an end can put the related nodes into this node's text index, so a venue is found by the names of its events, and makes the relation a facet:

[RelationProperty(
    TextIndexRelatedName = true,          // index the related nodes' names (IName.Name)
    TextIndexRelatedContent = false,      // true indexes their text as well
    TextIndexRecursiveLevelLimit = 1,     // how far related content is followed
    Facet = true)]                        // facets are opt-in for relations
EventsAtVenue.Events Events { get; }

Display and AllowInlineEditing on [RelationProperty] say how an editing interface shows the related nodes (§10).

10. Choosing between relation, reference and embedded#

This is the modelling choice you make most often.

Decision guide

• The data means nothing outside its parent, and you never query it on its own: embedded.
• You need the same target more than once, and never the reverse lookup: References<T>. Order alone is no reason to choose it: relation lists are ordered too, and can be reordered.
• You point at one thing, cheaply, and never ask "what points at me?": Reference<T>.
• You need reverse navigation, traversal, relation filters or facets, or a hand-curated order: relation. When in doubt, choose a relation.

In the running example:

• IVenue.Hours is embedded: opening hours mean nothing without their venue.
• IEvent.Cover is a Reference<IMediaAsset>: nobody asks an image which events use it.
• IEvent.Sponsors is a References<IOrganizer>: one organizer can appear twice, at different billing tiers. The duplicates rule out a relation.
• Event ↔ venue and event ↔ attendee are relations: both directions are read all the time, and a venue's events are ordered by hand.

How an editor shows them: Display#

Display says how an editing interface, such as the Relatude CMS, shows the nodes a property holds. It goes on [RelationProperty], [ReferenceProperty], [ReferencesProperty], [EmbeddedProperty] and [EmbeddedMapProperty]:

using Relatude.DB.Datamodels.Properties;   // DisplayMode

[RelationProperty(Display = DisplayMode.Table)]
EventsAtVenue.Events Events { get; }

[ReferencesProperty(Indexed = true, Display = DisplayMode.Cards)]
References<IOrganizer> Sponsors { get; }

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

Nodes of their own, those of a relation, reference or references property, are shown Inline only when the property says AllowInlineEditing = true; without it they are edited in editors of their own, and an editor does not offer Inline. Embedded nodes are the node's own values, so they can always be shown inline.

[ReferencesProperty(Display = DisplayMode.Inline, AllowInlineEditing = true)]
References<IArticle> Featured { get; }

The store ignores Display and AllowInlineEditing, so changing them rebuilds nothing. An application reads them from the property's model (RelationPropertyModel.Display, .AllowInlineEditing and the like). The admin UI's datamodel editor can change both (Display and Allow inline editing); for a type from compiled code, the change is saved as an override in the database (§3.1).

11. The complete example model#

Here is the whole running domain in one place. Parts II and III query this model.

Two details follow from §4. Organizers and venues inherit IName, so their Name is the node's name (Node names). An event's Title, an attendee's FullName and an asset's FileName are properties of their own, which §11.1 makes one name. Slug is the node's address, so it is read-only here: give a node its slug with UpdateAddress.

using Relatude.DB.Common;
using Relatude.DB.Datamodels;
using Relatude.DB.Native.Models;
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 : IName {
    Guid Id { get; set; }
    NodeMeta Meta { get; }

    [StringProperty(UniqueValues = true, IgnoreDuplicateEmptyValues = true)]   // unique, but may be empty
    string ContactEmail { get; set; }

    [AddressProperty]    string Slug { get; }
    [CreatedUtcProperty] DateTime CreatedUtc { get; }

    OrganizerEvents.Events Events { get; }
}

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

    [AddressProperty] string Slug { get; }

    [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. the complex a hall is in
    VenueTree.Children   Halls  { get; }
    EventsAtVenue.Events Events { get; }
}

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

    [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; }

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

    [StringProperty(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; }

    [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 on each type, so each type reads on its own. In a real project you would move the shared properties into facet interfaces, as in §2. Most of the repetition goes, and queries across types get simple.

One change comes with it: the names (Title, FullName, FileName) become one name, IName.Name, which INamedNode inherits. A shared name is worth it: it is what makes one search box, one list sorted by name and one "recently changed" feed possible. The enums, OpeningHours and the relation classes stay as above.

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

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

    [AddressProperty]    string Slug { get; }
    [CreatedUtcProperty] DateTime CreatedUtc { get; }
    [ChangedUtcProperty] DateTime ChangedUtc { get; }
}

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, MaxValue = "1.00:00:00")] 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(Indexed = true, UniqueValues = true)]
    string Email { get; set; }

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

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

    OrganizerEvents.Events Events { get; }
}

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