CRUD Operations

Document Types

Every document type must have a public Id property of type Guid, int, long, or string. The Id is stored in both the database Id column and inside the JSON blob, so query results always include it.

public class User
{
    public string Id { get; set; } = "";
    public string Name { get; set; } = "";
    public int Age { get; set; }
    public string? Email { get; set; }
}

Custom Id property

Designate a different property as the Id with MapIdProperty<T>(x => x.MyProperty) (type stays in the default shared table) or MapTypeToTable<T>("table", x => x.MyProperty) (combined with a dedicated table). The same type constraints (Guid, int, long, string) and auto-generation rules apply to the custom property.

Auto-generation rules

Id CLR Type	Default Value	Auto-Gen Strategy
Guid	Guid.Empty	Guid.NewGuid()
string	null or ""	Throws InvalidOperationException
int	0	MAX(CAST(Id AS INTEGER)) + 1 per TypeName
long	0	MAX(CAST(Id AS INTEGER)) + 1 per TypeName

When Insert is called with a default Id, the store auto-generates one for Guid, int, and long types and writes it back to the object. For string Ids, a default value throws an InvalidOperationException — you must always supply an explicit Id. When a non-default Id is provided, it is used as-is.

Custom Id types

To use an Id type beyond the four built-ins — a Ulid, or a strongly-typed wrapper such as record struct OrderId(Guid Value) — register a converter with MapIdType on the store options. The Id is still stored as a string in every provider, so there is no schema or on-disk change; the converter just defines how that string round-trips.

public readonly record struct OrderId(Guid Value)
{
    public static OrderId New() => new(Guid.NewGuid());
}

// Inline delegates:
options.MapIdType(
    toString:  (OrderId id) => id.Value.ToString("N"),
    parse:     s => new OrderId(Guid.ParseExact(s, "N")),
    isDefault: id => id.Value == Guid.Empty,   // when to auto-generate on Insert
    generate:  OrderId.New);                   // optional; omit to require explicit Ids

// …or a reusable class deriving from DocumentIdConverter<TId>:
public sealed class OrderIdConverter : DocumentIdConverter<OrderId>
{
    public override string  ToStorageString(OrderId id) => id.Value.ToString("N");
    public override OrderId FromStorageString(string s)  => new(Guid.ParseExact(s, "N"));
    public override bool    IsDefault(OrderId id) => id.Value == Guid.Empty;
    public override bool    TryGenerate(out OrderId id) { id = OrderId.New(); return true; }
}
options.MapIdType(new OrderIdConverter());

public class Order
{
    public OrderId Id { get; set; }      // default-named "Id" — no MapIdProperty needed
    public string Customer { get; set; } = "";
}

var order = new Order { Customer = "Alice" };
await store.Insert(order);                       // Id auto-generated via TryGenerate/generate
var fetched = await store.Get<Order>(order.Id);  // Get/Update/Remove accept the typed Id

MapIdType is available on every provider’s options class. The built-in Guid/int/long/string types need no registration and are unchanged.

Two places the Id lives

A document Id is stored in both the provider’s Id column/field and inside the serialized JSON Data blob. MapIdType controls the column/field; the JSON form is produced by System.Text.Json. Give a custom Id type a matching JsonConverter so both render the same string — otherwise LINQ predicates on the Id (Where(x => x.Id == value), which compare against the JSON) won’t line up.

Sortable (version 7) Guid Ids

For time-ordered, append-friendly Guid Ids, call UseGuidV7Ids() to auto-generate version 7 GUIDs (Guid.CreateVersion7()) instead of the default random version 4. No extra dependency — it’s BCL — and the storage format is unchanged, so it is a drop-in for existing Guid-keyed data (only newly generated Ids differ).

options.UseGuidV7Ids();   // every `Guid Id` now auto-generates a sortable v7 GUID

If you only want a non-Guid integral key, note long is already a built-in Id type (auto-generated as MAX(id) + 1 per type).

Insert a document

// Auto-generated ID (Guid) — written back to the object
public class UserGuid
{
    public Guid Id { get; set; }
    public string Name { get; set; } = "";
    public int Age { get; set; }
}

var user = new UserGuid { Name = "Alice", Age = 25 };
await store.Insert(user);
// user.Id is now populated

// Explicit ID (string)
await store.Insert(new User { Id = "user-1", Name = "Alice", Age = 25 });

Batch insert

BatchInsert inserts multiple documents in a single transaction with prepared command reuse for optimal performance. Returns the count inserted. If any document fails (e.g. duplicate Id), the entire batch is rolled back. Auto-generates IDs for Guid, int, and long Id types.

var users = Enumerable.Range(1, 1000).Select(i => new User
{
    Id = $"user-{i}", Name = $"User {i}", Age = 20 + (i % 50)
});

var count = await store.BatchInsert(users); // single transaction, prepared command reused

Batch upsert, update & remove

BatchUpsert, BatchUpdate, and BatchRemove apply many writes as one set operation instead of one round-trip per document, and they are all-or-nothing: on a versioned type the first version conflict throws ConcurrencyException and the whole batch rolls back.

await store.BatchUpsert(users);                          // RFC 7396 merge-or-insert, many at once
await store.BatchUpdate(users);                          // full replace, every doc must exist
int removed = await store.BatchRemove<User>(new object[] { "u1", "u2", "u3" }); // ids that don't exist are ignored

How much you save depends on the backend (the provider tier):

Backend	BatchUpsert	BatchUpdate	BatchRemove
SQLite, DuckDB	single multi-row INSERT … ON CONFLICT (deep merge)	per-row in one transaction	single DELETE … IN (…)
SQL Server, PostgreSQL, MySQL, Oracle	per-doc loop in one transaction¹	per-row in one transaction	single DELETE … IN (…)
MongoDB	one BulkWrite	one BulkWrite	one DeleteMany
Cosmos	bounded-concurrency waves²	bounded-concurrency waves²	bounded-concurrency waves²

¹ These providers lack a native deep-merge function, so BatchUpsert reuses the per-document read-merge-write inside one transaction. ² Cosmos has no cross-document transaction; batches run as parallel request waves (best-effort, matching the provider’s unit-of-work behaviour).

A type that has a version mapping, temporal history, a spatial/vector sidecar, multi-tenancy, a query filter, or a per-document interceptor always takes the per-document loop inside one transaction — correct and atomic, just not the multi-row/bulk fast path.

Unit of work (grouping writes atomically)

To apply several writes in a single transaction, create a UnitOfWork, queue operations, then call SaveChanges. Everything commits together or rolls back together. Contiguous same-type runs of inserts, upserts, updates, and removes are each coalesced into the matching batch method, so grouping like operations in a unit costs nothing versus calling those methods directly.

var uow = store.CreateUnitOfWork();
uow.Add(order)
   .AddRange(orderLines)        // coalesced into one batch insert
   .Update(customer)
   .Remove<Cart>(cartId);

await uow.SaveChanges();        // one transaction; rolls back entirely on failure

You only ever inject IDocumentStore — the unit is created from it, never registered in DI. A unit is a write buffer, not a tracking context: reads don’t see operations still buffered in an uncommitted unit. See the FAQ for the full write-API decision tree.

Breaking change in 8.0

RunInTransaction has been removed. Replace store.RunInTransaction(tx => …) with a UnitOfWork: queue your Add/Update/Upsert/Remove calls and await uow.SaveChanges().

Upsert with JSON Merge Patch

Upsert uses JSON merge patch (RFC 7396) to deep-merge a partial patch into an existing document. If the document doesn’t exist, it is inserted as-is. Unlike Update, which replaces the entire document, Upsert only overwrites the fields present in the patch. The document must have a non-default Id.

// Insert a full document
await store.Insert(new User { Id = "user-1", Name = "Alice", Age = 25, Email = "alice@test.com" });

// Merge patch — only update Name and Age, preserve Email
await store.Upsert(new User { Id = "user-1", Name = "Alice", Age = 30 });

var user = await store.Get<User>("user-1");
// user.Name == "Alice", user.Age == 30, user.Email == "alice@test.com" (preserved)

How it works:

• On insert (new ID): the patch is stored as the full document.
• On conflict (existing ID): the provider’s JSON merge function merges the patch into the stored JSON. Scalars and arrays are replaced.
• Null properties are excluded from the patch automatically. In C#, unset nullable properties (e.g. string? Email) serialize as null, which would remove the key under RFC 7396. The library strips these so that unset fields are preserved rather than deleted.

Note

For true partial updates, use nullable properties in your patch type so that unset fields are null and excluded from the merge. Non-nullable properties with default initializers (e.g. string Name = "") will always be included in the patch.

Merge depth varies by provider

Only SQLite, SQLCipher, MySQL, CosmosDB, LiteDB, and IndexedDB perform a true RFC 7396 deep merge — nested objects are recursively merged. PostgreSQL and SQL Server perform a shallow top-level merge only — sending a partial nested object replaces the whole sub-object and loses untouched nested fields. On those providers, either include all fields of nested objects in the patch, use SetProperty for individual nested fields, or use Update to replace the document. See Provider Reference for examples.

Update a single property (SetProperty)

SetProperty updates a single scalar field in-place using the provider’s JSON set function — no deserialization, no full document replacement. Returns true if the document was found and updated, false if not found. The id parameter accepts Guid, int, long, or string.

// Update a scalar field
await store.SetProperty<User>("user-1", u => u.Age, 31);

// Update a string field
await store.SetProperty<User>("user-1", u => u.Email, "newemail@test.com");

// Set a field to null
await store.SetProperty<User>("user-1", u => u.Email, null);

// Nested property
await store.SetProperty<Order>("order-1", o => o.ShippingAddress.City, "Portland");

// Check if document existed
bool updated = await store.SetProperty<User>("user-1", u => u.Age, 31);

How it works: The expression u => u.Age is resolved to the JSON path $.age (respecting [JsonPropertyName] attributes and naming policies). The generated SQL varies by provider — for example, SQLite uses json_set(), SQL Server uses JSON_MODIFY(), etc.

Supported value types: string, int, long, double, float, decimal, bool, and null. To replace a collection or nested object, use Update (full replacement) or Upsert (merge patch).

Remove a single property (RemoveProperty)

RemoveProperty strips a field from the stored JSON using the provider’s JSON remove function. Returns true if the document was found and updated, false if not found. The removed field will have its C# default value on next read. The id parameter accepts Guid, int, long, or string.

// Remove a nullable field
await store.RemoveProperty<User>("user-1", u => u.Email);

// Remove a nested property
await store.RemoveProperty<Order>("order-1", o => o.ShippingAddress.City);

// Remove a collection property (removes the entire array)
await store.RemoveProperty<Order>("order-1", o => o.Tags);

Unlike SetProperty, RemoveProperty works on any property type — scalar, nested object, or collection — because it simply removes the key from the JSON.

Choosing an update strategy

Operation	Use when	Scope	Collections
SetProperty	Changing one scalar field	Single field via JSON set	Scalar values only
RemoveProperty	Stripping a field from the document	Single field via JSON remove	Any property type
Upsert	Patching multiple fields at once	Deep merge via JSON merge patch	Replaces arrays (RFC 7396)
Update	Replacing the entire document	Full replacement	Full control
Insert	Inserting a new document	Strict insert, throws on duplicate	Throws for string default Ids
BatchInsert	Inserting many documents efficiently	Single transaction, prepared command	Auto-generates IDs; atomic rollback
BatchUpsert / BatchUpdate / BatchRemove	Applying many upserts / updates / removes at once	One set operation (multi-row or bulk where supported); all-or-nothing	Per-provider tier; ids missing on remove are ignored
GetDiff	Diffing local changes vs stored state	Read-only; returns RFC 6902 patch	Deep nested diff; arrays replaced as whole

Optimistic Concurrency (Row Versioning)

Map a version property on your document type for automatic optimistic concurrency checks. The version is stored inside the JSON blob — no schema or table changes required. Works across all providers.

Configuration

// Expression-based (reflection)
var store = new DocumentStore(new DocumentStoreOptions
{
    DatabaseProvider = new SqliteDatabaseProvider("Data Source=mydata.db")
}.MapVersionProperty<Order>(o => o.RowVersion));

// AOT-safe overload
var store = new DocumentStore(new DocumentStoreOptions
{
    DatabaseProvider = new SqliteDatabaseProvider("Data Source=mydata.db")
}.MapVersionProperty<Order>("RowVersion", o => o.RowVersion, (o, v) => o.RowVersion = v));

All provider options classes support MapVersionProperty: DocumentStoreOptions, LiteDbDocumentStoreOptions, CosmosDbDocumentStoreOptions, and IndexedDbDocumentStoreOptions.

How it works

Operation	Behavior
Insert	Version is set to 1 before serialization
Update	Reads the expected version from the object, checks it against the stored version, then increments. Throws ConcurrencyException on mismatch
Upsert	Insert path sets version to 1. Update path checks and increments (only when the existing version > 0)
BatchInsert	Version is set to 1 for each document
BatchUpsert / BatchUpdate / BatchRemove	Same per-document version rules as Upsert/Update; the batch is all-or-nothing — the first conflict throws ConcurrencyException and rolls the whole batch back

Example

public class Order
{
    public string Id { get; set; } = "";
    public string Status { get; set; } = "";
    public int RowVersion { get; set; }
}

// Insert — RowVersion is set to 1
var order = new Order { Id = "ord-1", Status = "Pending" };
await store.Insert(order);
// order.RowVersion == 1

// Update — RowVersion is checked and incremented
order.Status = "Shipped";
await store.Update(order);
// order.RowVersion == 2

// Concurrent update — throws ConcurrencyException
var staleOrder = new Order { Id = "ord-1", Status = "Cancelled", RowVersion = 1 };
await store.Update(staleOrder); // throws ConcurrencyException

ConcurrencyException

ConcurrencyException provides diagnostic properties:

Property	Description
TypeName	The document type name
DocumentId	The document Id
ExpectedVersion	The version the caller expected
ActualVersion	The version found in the store (when available)

try
{
    await store.Update(staleOrder);
}
catch (ConcurrencyException ex)
{
    Console.WriteLine($"Conflict on {ex.TypeName} {ex.DocumentId}: expected v{ex.ExpectedVersion}, found v{ex.ActualVersion}");
}

Get a document

The id parameter accepts Guid, int, long, or string. Passing an unsupported type throws ArgumentException.

var user = await store.Get<User>("user-1");

// Guid, int, and long Ids work directly — no ToString() needed
var item = await store.Get<GuidIdModel>(myGuid);
var order = await store.Get<IntIdModel>(42);

Diff against stored document (GetDiff)

Compare a modified object against the stored document and get an RFC 6902 JsonPatchDocument<T> describing the differences. Returns null if no document with that ID exists.

var proposed = new Order
{
    Id = "ord-1", CustomerName = "Alice", Status = "Delivered",
    ShippingAddress = new() { City = "Seattle", State = "WA" },
    Lines = [new() { ProductName = "Widget", Quantity = 10, UnitPrice = 8.99m }],
    Tags = ["priority", "expedited"]
};

var patch = await store.GetDiff("ord-1", proposed);
// patch.Operations:
//   Replace /status → Delivered
//   Replace /shippingAddress/city → Seattle
//   Replace /shippingAddress/state → WA
//   Replace /lines → [...]
//   Replace /tags → [...]

// Apply the patch to any instance of the same type
var current = await store.Get<Order>("ord-1");
patch!.ApplyTo(current!);

The diff is deep — nested objects produce individual property-level operations (e.g. /shippingAddress/city), while arrays and collections are replaced as a whole. Works with table-per-type, custom Id, and inside transactions.

Get all documents of a type

var users = await store.Query<User>().ToList();

Remove a document

The id parameter accepts Guid, int, long, or string. Passing an unsupported type throws ArgumentException.

// By ID
bool deleted = await store.Remove<User>("user-1");
bool removed = await store.Remove<GuidIdModel>(myGuid);

Remove documents matching a predicate

// Returns number of deleted rows
int deleted = await store.Query<User>().Where(u => u.Age < 18).ExecuteDelete();

Update documents matching a predicate

// Update a property on matching docs — returns number of updated rows
int updated = await store.Query<User>()
    .Where(u => u.Age < 18)
    .ExecuteUpdate(u => u.Age, 18);

See Querying for more examples of bulk delete and update with expressions.

Clear all documents of a type

int deletedCount = await store.Clear<User>();

Backup

Creates a hot backup of the database to a file. The store remains fully usable during the backup. Only available on concrete store types — not on the IDocumentStore interface.

Store	Behavior
SqliteDocumentStore	Uses the SQLite Online Backup API
SqlCipherDocumentStore	Backup is automatically encrypted with the same password
LiteDbDocumentStore	Requires a file-based connection string with a Filename parameter

// SQLite
var sqliteStore = new SqliteDocumentStore("Data Source=mydata.db");
await sqliteStore.Backup("/path/to/backup.db");

// SQLCipher — backup encrypted with same password
var cipherStore = new SqlCipherDocumentStore("encrypted.db", "mySecretKey");
await cipherStore.Backup("/path/to/backup.db");

// LiteDB
var liteStore = new LiteDbDocumentStore(new LiteDbDocumentStoreOptions
{
    ConnectionString = "Filename=mydata.db"
});
await liteStore.Backup("/path/to/backup.db");

Clear the entire store (ClearAll)

IDocumentMaintenance.ClearAll() wipes every document type in the store — including temporal-history, spatial, and vector sidecars. It’s intended for test and dev resets, not production use. Unlike Clear<T>() it is neither type- nor tenant-scoped; on a shared-table multi-tenant store it clears all tenants. It targets only your own (user) tables in the current database — system catalog schemas are never touched.

It’s an optional capability — probe for it with is IDocumentMaintenance:

if (store is IDocumentMaintenance maintenance)
    await maintenance.ClearAll();

Implemented on the relational DocumentStore (SQLite, SQL Server, PostgreSQL, MySQL, DuckDB, Oracle), MongoDB, and CosmosDB; verified across every provider suite.

ClearAllAsync on SQLite

SqliteDocumentStore.ClearAllAsync() still exists for back-compat and now simply delegates to ClearAll().

Seeding initial data

Register IDocumentSeeders to populate initial data once. The store is schema-free, so seeding is just idempotent writes — there is no schema to reconcile, and the same seeder works against every provider.

Run-once is versioned: each seeder records a DocumentSeedMarker keyed on its Name, and runs only when it has never run or when its Version is greater than the recorded one. Bump the version to re-run after changing seed data.

public class CountrySeeder : IDocumentSeeder
{
    public string Name => "countries";
    public int Version => 1;   // bump to re-run after editing the data below

    public async Task SeedAsync(IDocumentStore store, CancellationToken ct)
    {
        // Upsert on a known Id keeps it idempotent across re-runs
        await store.Upsert(new Country { Id = "CA", Name = "Canada" }, cancellationToken: ct);
        await store.Upsert(new Country { Id = "US", Name = "United States" }, cancellationToken: ct);
    }
}

Register it with DI — it runs once at host startup via a hosted service:

builder.Services.AddDocumentStore(o => o.DatabaseProvider = ...);
builder.Services.AddDocumentSeeder<CountrySeeder>();

// or inline, without a class:
builder.Services.AddDocumentSeeder("settings", version: 1, async (store, ct) =>
    await store.Upsert(new AppSettings { Id = "global", Theme = "dark" }, cancellationToken: ct));

To seed a named (keyed) store registered with AddDocumentStore("reporting", ...), pass storeName — seeders are grouped by target store and run against the right one:

builder.Services.AddDocumentSeeder<CountrySeeder>(storeName: "reporting");

Where there’s no generic host (e.g. a MAUI app), run the seeders yourself:

await DocumentSeedRunner.RunAsync(store, new IDocumentSeeder[] { new CountrySeeder() });

AOT

The internal DocumentSeedMarker is read/written through the store like any document. Under Native AOT (no reflection fallback), pass its JsonTypeInfo via the markerTypeInfo parameter on DocumentSeedRunner.RunAsync.