FoundationDB .NET — Keys, Values & Layers

FoundationDB is a single, flat, ordered key/value store. Both keys and values are byte strings. Keys are sorted lexicographically by their raw bytes, and that ordering is the only structure the database gives you — every "table", "index", "queue", or "document collection" is an illusion built by choosing key bytes carefully. Getting the key encoding right is therefore the whole game. This skill explains the idiomatic, type-safe API this client provides so you don't reinvent (incorrectly) what already exists.

If you remember one thing: you almost never touch raw bytes. You build keys with subspace.Key(...) and values with FdbValue.*, and you pass those objects directly to the transaction. The library renders them to bytes for you, efficiently, at the last moment.

---

1. The mental model

• A subspace is a key prefix. All keys you create live "inside" it. You get subspaces from a location resolved against a transaction (see §6). Never hard-code prefixes.
• Tuple encoding (TuPack) turns typed elements — strings, integers, GUIDs, booleans, VersionStamp, … — into bytes whose byte order matches the logical order of the values. (42, "hello") always sorts before (42, "world") and before (43, …). This order-preservation is why tuples are the default key encoding.
• A key in this API is a small struct (e.g. FdbTupleKey<string,int>) that remembers its subspace and its elements and knows how to render itself. It is lazy: no bytes exist until the transaction asks for them.
• A value is likewise a lightweight encodable (e.g. FdbRawValue, FdbVarTupleValue, FdbJsonValue) produced by FdbValue.*.

---

2. Golden rules (this is where vibe-coded usage goes wrong)

✅ DO

• Build keys with subspace.Key(a, b, c) and pass the result straight into tr.GetAsync(...) / tr.Set(...).
• Build values with FdbValue.ToBytes(...), FdbValue.FromTuple(...), FdbValue.ToTextUtf8(...), FdbValue.ToFixed64LittleEndian(...), FdbValue.ToJson(...).
• Decode keys with subspace.Decode<T1,...>(key) / DecodeLast<T> and values with the matching FdbValue/TuPack reader.
• Get a subspace by await location.Resolve(tr) inside the transaction.
• Use atomic mutations (tr.AtomicAdd64, AtomicIncrement64, …) for counters instead of read-modify-write.

❌ DON'T

• ❌ Don't eagerly serialize: var k = subspace.Key("a", 1).ToSlice(); tr.Set(k, ...). Pass the key object itself; .ToSlice() forces an allocation you don't need. (.ToSlice() is for tests/logging/storing a key as a value.)
• ❌ Don't build keys by hand with string concatenation, Encoding.UTF8.GetBytes, BitConverter, +, or manual separators ("\x00", ":", "/"). You will break ordering and escaping. Use tuples.
• ❌ Don't hard-code or cache a subspace prefix across transactions. Prefixes can change (Directory layer); resolve every transaction.
• ❌ Don't cache the resolved subspace / layer State outside the transaction that produced it (see §7).
• ❌ Don't reach for TuPack.EncodeKey(...) to make database keys directly when you have a subspace — subspace.Key(...) already applies the prefix and tuple-encodes. (TuPack is the lower-level primitive; use it for values or when you genuinely have no subspace.)
• ❌ Don't store a Guid in a key without realizing it uses the custom tuple type codes (0x30 for 128-bit) — that's handled for you by tuple encoding; just don't re-encode it as bytes yourself.
• ❌ Don't use raw, unnamed literals to discriminate the sub-parts of a subspace (data vs index vs metadata). Use named constants, and prefer small integers for compactness: 0 packs to 1 byte (0x14), 1 to 2 bytes (0x15 0x01), whereas "D" costs 3 bytes (0x02 'D' 0x00) on every key. (Short named strings like "T"/"S" are a legitimate choice some layers make for readability in raw dumps — just be deliberate and consistent; see §7.)
• ❌ Don't trust a caller-supplied entity to locate index keys for an update/delete. Its indexed fields may be stale, leaving orphaned index entries. Read the stored document and derive the old index key from that (see §7).

---

3. Building keys

subspace.Key(...) is the workhorse. It packs the subspace prefix followed by the tuple-encoded arguments, and returns a strongly-typed key:

IKeySubspace subspace = /* resolved, see §6 */;

FdbTupleKey<string>            k1 = subspace.Key("hello");                 // prefix + ("hello",)
FdbTupleKey<string, int>       k2 = subspace.Key("hello", 123);           // prefix + ("hello", 123)
FdbTupleKey<string, int, Guid> k3 = subspace.Key("user", 123, userId);
FdbSubspaceKey                 kp = subspace.Key();                        // the prefix itself (a key)

Other constructors:

// From an existing tuple value (STuple or ValueTuple):
subspace.Tuple(STuple.Create("hello", 123));
subspace.Tuple(("hello", 123));

// A raw binary suffix appended to the subspace (NOT tuple-encoded) — use only for interop
// with externally-defined byte layouts:
FdbSuffixKey raw = subspace.Bytes(someReadOnlySpanOfBytes);

// A fully pre-encoded standalone key (no subspace):
FdbRawKey r = FdbKey.FromBytes(slice);
FdbTupleKey<string,int> t = FdbKey.FromTuple(("hello", 123));   // packs in the root keyspace

// System / special keys (\xFF...):
FdbSystemKey sys = FdbKey.ToSystemKey("/metadataVersion");

Keys implement IFdbKey and are accepted directly by every transaction method. The key is rendered into pooled buffers (or the stack, for short keys) inside the call — you don't manage that.

Slice value = await tr.GetAsync(subspace.Key("user", 123));
tr.Set(subspace.Key("user", 123), FdbValue.FromTuple(("Alice", 30)));
tr.Clear(subspace.Key("user", 123));

.ToSlice() exists, but only use it when you need the bytes as data (logging, tests, or storing a key inside a value).

Typed prefix + a runtime tuple (dynamic tails)

When part of the key is fixed and typed but the tail isn't known at compile time — e.g. a generic index whose indexed value is an arbitrary IVarTuple — chain .Tuple(...) onto a typed .Key(...):

IVarTuple value = collation.Collate(rawValue);          // built at runtime, arbitrary element types
var indexKey = subspace.Key(INDEXES, indexId).Tuple(value);   // typed prefix (1, idx) + dynamic suffix

subspace.Key(a, b) gives the strongly-typed prefix; .Tuple(ivarTuple) appends the runtime elements. This is the idiomatic replacement for hand-packing — and for the old subspace.Pack(STuple.Create(a, b).Concat(value)) style (see §11). Convert a key into a child subspace with key.ToSubspace() (e.g. subspace.Key(tenantId).ToSubspace() to partition by tenant).

VersionStamp keys — globally-ordered, monotonic ids

For queues, event logs, inboxes — anything that needs insertion-ordered, collision-free keys across all writers — append a VersionStamp assigned by the database at commit time:

var stamp = tr.CreateVersionStamp(userVersion);          // an *incomplete* stamp (filled in at commit)
tr.SetVersionStampedKey(inbox.Key(stamp), payload);      // FDB writes the real, monotonic stamp on commit

• The stamp is monotonic and globally ordered, so a plain range scan returns items in commit order — no client-side sequence number, no contention on a shared counter.
• CreateVersionStamp(int userVersion) (vs the arg-less form) disambiguates multiple stamped keys written in the same transaction — pass an incrementing userVersion per item.
• You must use SetVersionStampedKey (not Set) so the database knows to substitute the real stamp; the key you build carries the incomplete stamp as a placeholder.
• To put the stamp in the value instead (e.g. a "last write" marker), use tr.SetVersionStampedValue(key, tr.CreateVersionStamp()).
• Read it back with VersionStamp.ReadFrom(...) / subspace.Decode<…, VersionStamp>(key), and trim consumed entries with a cursor range (key.ToHeadRangeInclusive(cursor)).

---

4. Ranges & key derivation

Most layers read ranges, not single keys. Build ranges from keys/subspaces — never by manually incrementing bytes.

// Everything under the subspace:
tr.GetRange(subspace.ToRange());                       // prefix\x00 .. prefix\xFF  (children)
subspace.ToRange(inclusive: true);                     // also includes the prefix key itself

// Everything under a key prefix (e.g. all entries for one user):
tr.GetRange(subspace.Key("user", 123).ToRange());      // ("user",123, *)

// Explicit bounds:
FdbKeyRange.Single(subspace.Key(123));                 // exactly that one key
FdbKeyRange.Between(subspace.Key(100), subspace.Key(200));   // [100, 200)
subspace.ToHeadRange(cursor);                          // subspace start .. cursor
subspace.ToTailRange(cursor);                          // cursor .. subspace end

Derivation helpers (extension methods on any key) — these produce new keys/selectors with correct byte math:

Helper	Meaning
key.Successor()	key + \x00 — the immediately following key (e.g. exclusive lower bound)
key.NextSibling()	first key that does not have key as a prefix (i.e. Increment) — exclusive upper bound over key's children
subspace.First() / subspace.Last()	first / last possible child key of the subspace
key.FirstGreaterOrEqual() / key.LastLessOrEqual()	KeySelectors for GetKey/range bounds

Idiom for "all index entries with value v, ordered":

// inclusive range over (v, *):
tr.GetRangeKeys(subspace.Key(v).ToRange(inclusive: true), subspace, (s, k) => s.DecodeLast<TId>(k)!);

---

5. Decoding keys back to values

When you read a range, you get raw key bytes. Turn them back into typed values with the same subspace that produced them:

foreach (var kv in chunk)
{
    // full key (elements are nullable: STuple<string?, int?>):
    var (name, id) = subspace.Decode<string, int>(kv.Key);
    // just the first / last element of the tuple after the prefix:
    int id2  = subspace.DecodeLast<int>(kv.Key);
    string n = subspace.DecodeFirst<string>(kv.Key);
    // or the whole thing as a tuple:
    IVarTuple t = subspace.Unpack(kv.Key);
}

Decode<T...> strips the subspace prefix and tuple-decodes the remainder. Use it; don't slice bytes by hand.

Hot path, no allocation: Unpack and Decode allocate a Range[] per call for the element boundaries. In a tight decode loop, size a Span<Range> with TuPack.CountItems, then read from the returned SpanTuple:

Span<Range> buffer = stackalloc Range[TuPack.CountItems(kv.Key.Span)];
SpanTuple t = subspace.Unpack(kv.Key.Span, buffer); // t is backed by buffer: keep it alive and untouched while t is used
int id = t.Get<int>(1);

TuPack.Unpack(ReadOnlySpan<byte>, Span<Range>) is the raw form, and IKeySubspace.Unpack(ReadOnlySpan<byte>, Span<Range>) its subspace form. A buffer too small throws ArgumentException; TryUnpack returns false.

---

6. Subspaces, locations, and the Directory layer

You should never invent a prefix. You declare a logical path and let the Directory layer map it to a short, dense binary prefix:

// A location is a logical pointer; resolving it yields the actual subspace+prefix for THIS transaction.
// db.Root is indexed by path SEGMENT — chain the indexer to descend one segment at a time:
ISubspaceLocation location = db.Root["Tenants"]["ACME"]["Documents"]["Books"];
// or build the path explicitly:
//   db.Root[FdbPath.Relative("Tenants", "ACME", "Documents", "Books")]

await db.WriteAsync(async tr =>
{
    IKeySubspace subspace = await location.Resolve(tr);   // queries the Directory layer, caches per-tx
    tr.Set(subspace.Key("BOOK_123"), FdbValue.FromTuple(("Title", "ISBN")));
}, ct);

⚠️ Indexer gotcha: db.Root["a", "b"] is not two path segments — the 2-string overload is this[string name, string layerId], so "b" is interpreted as a layer id on segment "a". For multiple segments, chain the indexer (db.Root["a"]["b"]) or pass an FdbPath.

• location.Resolve(tr) returns the resolved IKeySubspace. TryResolve(tr) returns null if the directory doesn't exist yet.
• The resolved prefix (e.g. two bytes like \x15\x2A) is shared by every key in the subspace, so keys stay tiny.
• Resolve every transaction. The mapping is stable in practice but is not guaranteed forever; caching the prefix yourself defeats the Directory layer and risks corruption.
• For ad-hoc/manual prefixes (tests, fixed system areas) you can use KeySubspace.FromKey(prefix) or db.Root.WithPrefix(...), but prefer named paths in real applications.

---

7. Writing a custom Layer

A Layer is the FoundationDB equivalent of a small data-access component (a map, an index, a queue, a document collection). The canonical shape, used by every layer in FoundationDB.Layers.Common, is:

1. The layer class is a thin, reusable wrapper over an ISubspaceLocation (+ codecs/options). It holds no per-transaction state.
2. It implements IFdbLayer<TState>. Resolve(tr) resolves the location and returns a State object that holds the resolved IKeySubspace (and a back-reference to the layer). Memoize it in tr.Context (via TryGetLocalData/GetOrCreateLocalData) so repeated Resolve(tr) calls within one transaction are free — every production layer does this.
3. All real work is methods that take an IFdbTransaction / IFdbReadOnlyTransaction and use the State's subspace to build keys.
4. The State must never escape the transaction — don't store it in a field, don't return it to the caller, don't reuse it in the next retry. (tr.Context local data is per-transaction, so memoizing there is safe; a layer field is not.)

Worked example — a typed document collection

using FoundationDB.Client;
using SnowBank.Data.Tuples;   // STuple, TuPack
using SnowBank.Data.Json;     // CrystalJson
using SnowBank.Linq;          // IAsyncQuery

/// <summary>Stores Book documents (as JSON) keyed by their Id, plus a secondary index by author.</summary>
public sealed class BookStore : IFdbLayer<BookStore.State>
{
    // Discriminate the sub-parts of the subspace with small INTEGER constants, not strings.
    // Tuple-packed, 0 is 1 byte (0x14) and 1 is 2 bytes (0x15 0x01); the string "D" would be
    // 3 bytes (0x02 'D' 0x00) on *every* key. Name them so call sites read clearly.
    private const int SUBSPACE_DOCUMENTS = 0;      // (0, <id>)            -> json document
    private const int SUBSPACE_INDEX_AUTHOR = 1;   // (1, <author>, <id>) -> empty (index entry)

    /// <summary>LayerId advertised to the Directory layer, linking subspaces to the SchemaMapper.</summary>
    public const string LayerId = "docstore.Books";

    public BookStore(ISubspaceLocation location)
    {
        this.Location = location;
    }

    public ISubspaceLocation Location { get; }

    public string Name => nameof(BookStore);

    private const string LocalDataKey = nameof(BookStore);

    // Resolve once per transaction; memoize in the transaction's local data so repeated
    // Resolve(tr) calls in the same tx reuse the same State. Never cache it OUTSIDE the tx.
    public ValueTask<State> Resolve(IFdbReadOnlyTransaction tr)
    {
        if (tr.Context.TryGetLocalData(LocalDataKey, out State? state))
        {
            return new ValueTask<State>(state);
        }
        return ResolveSlow(this, tr);

        static async ValueTask<State> ResolveSlow(BookStore self, IFdbReadOnlyTransaction tr)
        {
            var subspace = await self.Location.Resolve(tr);
            return tr.Context.GetOrCreateLocalData(LocalDataKey, new State(self, subspace));
        }
    }

    public sealed class State
    {
        private readonly BookStore Layer;
        public IKeySubspace Subspace { get; }

        internal State(BookStore layer, IKeySubspace subspace)
        {
            this.Layer = layer;
            this.Subspace = subspace;
        }

        /// <summary>Inserts a brand-new book (assumes the Id does not already exist).</summary>
        public void Insert(IFdbTransaction tr, Book book)
        {
            tr.Set(this.Subspace.Key(SUBSPACE_DOCUMENTS, book.Id), FdbValue.ToJson(book));
            tr.Set(this.Subspace.Key(SUBSPACE_INDEX_AUTHOR, book.Author, book.Id), FdbValue.Empty);
        }

        /// <summary>Reads a book by Id, or null if missing.</summary>
        public async Task<Book?> GetAsync(IFdbReadOnlyTransaction tr, string id)
        {
            var bytes = await tr.GetAsync(this.Subspace.Key(SUBSPACE_DOCUMENTS, id));
            // CrystalJson.Deserialize maps a Nil/empty slice (missing key) to null already —
            // no `bytes.IsNull ? null : ...` guard needed.
            return CrystalJson.Deserialize<Book>(bytes);
        }

        /// <summary>Updates a book by re-reading the stored document to learn the old indexed value.
        /// Use when the caller does NOT already hold the original. The re-read costs no extra network
        /// round-trip if the key was already read in this tx, but does re-deserialize the JSON.</summary>
        public async Task UpdateAsync(IFdbTransaction tr, Book book)
        {
            Book? old = CrystalJson.Deserialize<Book>(
                await tr.GetAsync(this.Subspace.Key(SUBSPACE_DOCUMENTS, book.Id)));

            tr.Set(this.Subspace.Key(SUBSPACE_DOCUMENTS, book.Id), FdbValue.ToJson(book));
            ReindexAuthor(tr, book.Id, old?.Author, book.Author);
        }

        /// <summary>Updates a book when the caller ALREADY holds the original.
        /// CONTRACT: <paramref name="original"/> MUST be the exact value returned by GetAsync(...) on
        /// THIS SAME transaction — that read registers the conflict that keeps the index consistent.
        /// Passing a stale or foreign "original" WILL corrupt the index. No read is done here.</summary>
        public Task UpdateAsync(IFdbTransaction tr, Book updated, Book original)
        {
            tr.Set(this.Subspace.Key(SUBSPACE_DOCUMENTS, updated.Id), FdbValue.ToJson(updated));
            ReindexAuthor(tr, updated.Id, original.Author, updated.Author);
            return Task.CompletedTask;
        }

        /// <summary>Reads, mutates and saves a book in one call. <paramref name="patch"/> gets the current
        /// document and returns the modified copy (records: a `with` expression). Nothing is written if the
        /// patch is a no-op; the index is only touched if the author changed. Ideal for cheap field bumps.</summary>
        public async Task<Book?> PatchAsync(IFdbTransaction tr, string id, Func<Book, Book> patch)
        {
            Book? current = CrystalJson.Deserialize<Book>(
                await tr.GetAsync(this.Subspace.Key(SUBSPACE_DOCUMENTS, id)));
            if (current is null) return null; // nothing to patch

            Book updated = patch(current);

            if (updated == current) return current; // no-op: records compare by value -> skip all writes

            if (!string.Equals(updated.Id, id, StringComparison.Ordinal))
                throw new InvalidOperationException("A patch must not change the document Id.");

            tr.Set(this.Subspace.Key(SUBSPACE_DOCUMENTS, id), FdbValue.ToJson(updated));
            ReindexAuthor(tr, id, current.Author, updated.Author);
            return updated;
        }

        /// <summary>Deletes a book by Id (and its index entry). Takes only the Id — see note below.</summary>
        public async Task<bool> DeleteAsync(IFdbTransaction tr, string id)
        {
            // Trust ONLY the stored document for the indexed value, never a caller-supplied Book.
            Book? existing = CrystalJson.Deserialize<Book>(
                await tr.GetAsync(this.Subspace.Key(SUBSPACE_DOCUMENTS, id)));
            if (existing is null) return false; // nothing to delete

            tr.Clear(this.Subspace.Key(SUBSPACE_DOCUMENTS, id));
            tr.Clear(this.Subspace.Key(SUBSPACE_INDEX_AUTHOR, existing.Author, id));
            return true;
        }

        /// <summary>Ids of all books by an author, in order.</summary>
        public IAsyncQuery<string> FindIdsByAuthor(IFdbReadOnlyTransaction tr, string author)
        {
            // range over (1, author, *), pull the <id> back out of each key
            return tr
                .GetRange(this.Subspace.Key(SUBSPACE_INDEX_AUTHOR, author).ToRange())
                .Select(kv => this.Subspace.DecodeLast<string>(kv.Key)!);
        }

        // Moves the author index entry for `id`, but only when the indexed value actually changed.
        private void ReindexAuthor(IFdbTransaction tr, string id, string? oldAuthor, string newAuthor)
        {
            if (oldAuthor is null)
            {
                tr.Set(this.Subspace.Key(SUBSPACE_INDEX_AUTHOR, newAuthor, id), FdbValue.Empty);
            }
            else if (!string.Equals(oldAuthor, newAuthor, StringComparison.Ordinal))
            {
                tr.Clear(this.Subspace.Key(SUBSPACE_INDEX_AUTHOR, oldAuthor, id));
                tr.Set(this.Subspace.Key(SUBSPACE_INDEX_AUTHOR, newAuthor, id), FdbValue.Empty);
            }
            // else: unchanged -> leave the index alone (no wasted write, no extra conflict)
        }
    }

    /// <summary>Describes this layer's key layout so tools (db dumps, the FQL shell, loggers) can render
    /// raw keys as friendly tuples. Any directory subspace tagged with <see cref="LayerId"/> uses these rules.</summary>
    public sealed class SchemaMapper : IFdbLayerSchemaMapper
    {
        public string LayerId => BookStore.LayerId;

        public IEnumerable<FqlTemplateExpression> GetRules()
        {
            // (0, <id:string>) -> a JSON document
            yield return new FqlTemplateExpression(
                "document",
                FqlTupleExpression.Create().Integer(SUBSPACE_DOCUMENTS).VarString("id"),
                FdbValueTypeHint.Json);

            // (1, <author:string>, <id:string>) -> empty index entry
            yield return new FqlTemplateExpression(
                "index.author",
                FqlTupleExpression.Create().Integer(SUBSPACE_INDEX_AUTHOR).VarString("author").VarString("id"),
                FdbValueTypeHint.None);
        }
    }
}

public sealed record Book
{
    public required string Id { get; init; }
    public required string Author { get; init; }
    public required string Title { get; init; }
}

Maintaining a secondary index correctly

The index entries ((1, <author>, <id>)) are derived data — your code, not the database, keeps them in sync with the documents. This is where layers most often go wrong:

• Prefix sub-parts with named constants — prefer small integers. subspace.Key(SUBSPACE_DOCUMENTS, id) packs the discriminator in 1 byte; subspace.Key("D", id) costs 3 bytes on every key (and every index key). Define private const int … for compactness. Short named strings are a valid readability tradeoff (some production layers use "T"/"S"), but never inline raw literals.
• To change the index you must know the OLD indexed value. And you can only obtain it from the stored document, never from an object the caller hands you (it may be stale or mutated, which would leave an orphaned index entry). The shared ReindexAuthor(...) helper moves the entry only when the value actually changed, so an update that doesn't touch the author writes nothing to the index.
• Every index mutation happens in the same transaction as the document mutation, so the index can never drift out of sync on a partial failure.

The example offers three update flavors, trading a read against caller obligations: