File collections

Files next to your documents

Besides document collections, NetlyDB provides file collections for arbitrary binary data - images, PDFs, video, exports. Each file is a FileData payload: name, extension, content type, bytes, an optional virtual folder path, and tags. File content is stored compressed; metadata and tags stay queryable without loading the content.

Resolve IFileStore from dependency injection (registered by AddNetlyDB). GetCollection(name) opens or creates a collection; CreateCollection(name) registers one explicitly.

using NetlyDB.Core.Collections.FileCollections;
using NetlyDB.Core.Stores;

// IFileStore is registered by AddNetlyDB()
var fileStore = host.Services.GetRequiredService<IFileStore>();

fileStore.CreateCollection("uploads"); // optional; GetCollection also creates on first use
var uploads = fileStore.GetCollection("uploads");

Upload and read files

var bytes = await File.ReadAllBytesAsync("report.pdf");

Guid? id = uploads.Add(new FileData
{
    FileName = "report.pdf",
    Extension = ".pdf",
    ContentType = "application/pdf",
    Bytes = bytes,
    VirtualFolderPath = "invoices/2026", // the folder shown in the Management UI
    Tags = ["finance", "q1"]
});

// Stream the decompressed content (preferred for large files)
await using var stream = uploads.OpenRead(id!.Value);

// Or load the full document, bytes included
var document = uploads.GetById(id!.Value) as FileDocument;

uploads.Delete(id!.Value);

Metadata and streaming

GetMetaData and GetAllMetaData list files by name, size, content type, virtual folder or tags without reading content. OpenRead returns a decompressed Stream for downloads and media playback; GetById loads the full FileDocument, bytes included.

FileMetaData meta = uploads.GetMetaData(id!.Value);
// meta.FileName, meta.Size, meta.ContentType, meta.VirtualFolderPath, meta.Tags

foreach (var entry in uploads.GetAllMetaData())
{
    Console.WriteLine($"{entry.FileName} ({entry.Size} bytes)");
}

Tag queries

Filter files by one or more tags with WhereByTagAsync or WhereByTagsAsync (all tags must match by default).

var gallery = await uploads.WhereByTagAsync("gallery");
var q1Reports = await uploads.WhereByTagsAsync(
    ["finance", "q1"],
    matchAll: true);

In the Management UI Enterprise

The Management UI's file browser renders a folder tree from each file's VirtualFolderPath, uploads into a chosen folder, filters by tags (all or any), and shows thumbnails for images and videos, with a short inline preview when you hover a video. Only PNG, JPEG, GIF and WebP images and common audio and video types are displayed in the browser; every other file type is downloaded, never opened. Image thumbnails are not available when the UI runs in an arm64 process (including macOS on Apple silicon). See Management UI.

Over the REST API Enterprise

POST /Collections/file/uploads
GET  /Collections/uploads/count
GET  /Collections/names

File collections appear alongside document collections in GET /Collections/names and GET /Collections/infos.

Things to know

• File collections have no full-text or vector indexes; search operates on document collections.
• In a cluster, conflicting file changes resolve on wall-clock timestamps, without the clock-skew hardening that document replication has.