Ayende @ Rahien

The hole in my falloaction

Thu, 05 Feb 2026 12:00:00 GMT

I am working a bit with sparse files, and I need to output the list of holes in my file.

To my great surprise, I found that my file had more holes than I put into it. This probably deserves a bit of explanation.

If you know what sparse files are, feel free to skip this explanation:

A sparse filereduces disk space usage by storing only the non-zero data blocks.Zero-filled regions ("holes") are recorded as file system metadata only.
The file still has the same “size”, but we don’t need to dedicate actual disk space for ranges that are filled with zeros, we can just remember that there are zeros there. This is a natural consequence of the fact that files aren’t actually composed of linear space on disk.
Filesystems grow files using extents (contiguous disk chunks).A file initially gets a single extent (e.g., 1MB).Fast I/O is maintained as sequential data fills this contiguous block.Once the extent is full, the filesystem allocates a new, separate extent (which will not reside next to the previous one, most likely).The file's logical size grows continuously, but physical allocation occurs in discrete bursts as new extents are dynamically added.
If you are old enough to remember running defrag, that was essentially what it did. Ensured that the whole file was a single continuous allocation on disk. Because of this, it is very simple for a file system to just record holes, and the only file system that you’ll find in common use today that doesn’t support it is FAT.

At any rate, I had a problem. My file has more holes than expected, and that is not a good thing. This is the sort of thing that calls for a “Stop, investigate, blog” reaction. Hence, this post.

Let’s see a small example that demonstrates this:

#define _GNU_SOURCE
#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>


int main()
{
    const off_t file_size = 1024LL * 1024 * 1024;
    int fd = open("test-sparse-file.dat", O_CREAT | O_RDWR | O_TRUNC, 0644);
    fallocate(fd, 0, 0, file_size);
    
    off_t offset = 0;
    while (offset < file_size) {
        off_t hole_start = lseek(fd, offset, SEEK_HOLE);
        if (hole_start >= file_size) break;
        
        off_t hole_end = lseek(fd, hole_start, SEEK_DATA);
        if (hole_end < 0) hole_end = file_size;
        
        printf("Start: %.2f MB, End: %.2f MB\n", 
               hole_start / (1024.0 * 1024.0),
               hole_end / (1024.0 * 1024.0));
        
        offset = hole_end;
    }
    
    close(fd);
    return 0;
}

If you run this code, you’ll see this surprising result:

Start: 0.00 MB, End: 1024.00 MB

In other words, even though we just use fallocate() to ensure that we reserved the disk space, as far as lseek() is concerned, it is just one big hole. What is going on here?

Let’s dig a little deeper, using filefrag:

$ filefrag -b1048576 -v test-sparse-file.dat 
Filesystem type is: ef53
File size of test-sparse-file.dat is 1073741824 (1024 blocks of 1048576 bytes)
 ext:     logical_offset:        physical_offset: length:   expected: flags:
   0:        0..      23:     165608..    165631:     24:             unwritten
   1:       24..     151:     165376..    165503:    128:     165632: unwritten
   2:      152..     279:     165248..    165375:    128:     165504: unwritten
   3:      280..     407:     165120..    165247:    128:     165376: unwritten
   4:      408..     535:     164992..    165119:    128:     165248: unwritten
   5:      536..     663:     164864..    164991:    128:     165120: unwritten
   6:      664..     791:     164736..    164863:    128:     164992: unwritten
   7:      792..     919:     164608..    164735:    128:     164864: unwritten
   8:      920..    1023:     164480..    164583:    104:     164736: last,unwritten,eof
test-sparse-file.dat: 9 extents found

You can see that the file is made of 9 separate extents. The first one is 24MB in size, then 7 extents that are 128MB each, and the final one is 104MB.

Amusingly enough, the physical layout of the file is in reverse order to the logical layout of the file. That is just the allocation pattern of the file system, since there is no relation between the two.

Now, let’s try to figure out what is going on here. Do you see the flags on those extents? It says unwritten. That means this is physical space that was allocated to the file, but the file system is aware that it never wrote to that space. Therefore, that space must be zero.

In other words, conceptually, this unwritten space is no different from a sparse region in the file. In both cases, the file system can just hand me a block of zeros when I try to access it.

The question is, why is the file system behaving in this manner? And the answer is that this is an optimization. Instead of reading the data (which we know to be zeros) from the disk, we can just hand it over to the application directly. That saves on I/O, which is quite nice.

Consider the typical scenario of allocating a file and then writing to it. Without this optimization, we would literally double the amount of I/O we have to do.

It turns out that this optimization also applies to Windows and Mac, but the reason I ran into that on Linux is that I used the lseek(SEEK_HOLE), which considers the unwritten portion as a sparse hole as well. This makes sense, since if I want to copy data and I am aware of sparse regions, I should treat the unwritten portions as holes as well.

You can use the ioctl(FS_IOC_FIEMAP) to inspect the actual file extents (this is what filefrag does) if you actually care about the difference.

A tale of one-off, coding agents and the shortest path to victory

Mon, 02 Feb 2026 12:00:00 GMT

I needed to export all the messages from one of our Slack channels. Slack has a way of exporting everything, but nothing that could easily just give me all the messages in a single channel.

There are tools like slackdump or Slack apps that I could use, and I tried, but I got lost trying to make it work. In frustration, I opened VS Code and wrote:

I want a simple node.js that accepts a channel name from Slack and export all the messages in the channel to a CSV file

The output was a single script and instructions on how I should register to get the right token. It literally took me less time to ask for the script than to try to figure out how to use the “proper” tools for this.

The ability to do these sorts of one-off things is exhilarating.

Keep in mind: this isn’t generally applicable if you need something that would actually work over time. See my other post for details on that.

API Design: Don't try to guess

Thu, 29 Jan 2026 12:00:00 GMT

I was reviewing some code, and I ran into the following snippet. Take a look at it:

public void AddAttachment(string fileName, Stream stream)
   {
       ValidationMethods.AssertNotNullOrEmpty(fileName, nameof(fileName));
       if (stream == null)
           throw new ArgumentNullException(nameof(stream));


       string type = GetContentType(fileName);


       _attachments.Add(new PutAttachmentCommandData("__this__", fileName, stream, type, changeVector: string.Empty));
   }


   private static string GetContentType(string fileName)
   {
       var extension = Path.GetExtension(fileName);
       if (string.IsNullOrEmpty(extension))
           return "image/jpeg"; // Default fallback


       return extension.ToLowerInvariant() switch
       {
           ".jpg" or ".jpeg" => "image/jpeg",
           ".png" => "image/png",
           ".webp" => "image/webp",
           ".gif" => "image/gif",
           ".pdf" => "application/pdf",
           ".txt" => "text/plain",
           _ => "application/octet-stream"
       };
   }

I don’t like this code because the API is trying to guess the intent of the caller. We are making some reasonable inferences here, for sure, but we are also ensuring that any future progress will require us to change our code, instead of letting the caller do that.

In fact, the caller probably knows a lot more than we do about what is going on. They know if they are uploading an image, and probably in what format too. They know that they just uploaded a CSV file (and that we need to classify it as plain text, etc.).

This is one of those cases where the best option is not to try to be smart. I recommended that we write the function to let the caller deal with it.

It is important to note that this is meant to be a public API in a library that is shipped to external customers, so changing something in the library is not easy (change, release, deploy, update - that can take a while). We need to make sure that we aren’t blocking the caller from doing things they may want to.

This is a case of trying to help the user, but instead ending up crippling what they can do with the API.

Swiping left on writing authentication code yourself

Wed, 07 Jan 2026 12:00:00 GMT

You may have heard about a recent security vulnerability in MongoDB (MongoBleed). The gist is that you can (as an unauthenticated user) remotely read the contents of MongoDB’s memory (including things like secrets, document data, and PII). You can read the details about the actual technical issue in the link above.

The root cause of the problem is that the authentication process for MongoDB uses MongoDB’s own code. That sounds like a very strange statement, no? Consider the layer at which authentication happens. MongoDB handles authentication at the application level.

Let me skip ahead a bit to talk about how RavenDB handles the problem of authentication. We thought long and hard about that problem when we redesigned RavenDB for the 4.0 release. One of the key design decisions we made was to not handle authentication ourselves.

Authentication in RavenDB is based on X.509 certificates. That is usually the highest level of security you’re asked for by enterprises anyway, so RavenDB’s minimum security level is already at the high end. That decision, however, had a lot of other implications.

RavenDB doesn’t have any code to actually authenticate a user. Instead, authentication happens at the infrastructure layer, before any application-level code runs. That means that at a very fundamental level, we don’t deal with unauthenticated input. That is rejected very early in the process.

It isn’t a theoretical issue, by the way. A recent CVE was released for .NET-based applications (of which RavenDB is one) that could lead to exactly this issue, an authentication bypass problem.RavenDB is not vulnerable as a result of this issue because the authentication mechanism it relies on is much lower in the stack.

By the same token, the code that actually performs the authentication for RavenDB is the same code that validates that your connection to your bank is secure from hackers. On Linux - OpenSSL, on Windows - SChannel. These are already very carefully scrutinized and security-critical infrastructure for pretty much everyone.

This design decision also leads to an interesting division inside RavenDB. There is a very strict separation between authentication-related code (provided by the platform) and RavenDB’s.

The problem for MongoDB is that they reused the same code for reading BSON documents from the network as part of their authentication mechanism.

That means that any aspect of BSON in MongoDB needs to be analyzed with an eye toward unauthenticated user input, as this CVE shows.

An attempt to add compression support to reduce network traffic resulted in size confusion, which then led to this problem. To be clear, that is a very reasonable set of steps that happened. For RavenDB, something similar is plausible, but not for unauthorized users.

What about Heartbleed?

The name Mongobleed is an intentional reference to a very similar bug in OpenSSL from over a decade ago, with similar disastrous consequences. Wouldn’t RavenDB then be vulnerable in the same manner as MongoDB?

That is where the choice to use the platform infrastructure comes to our aid. Yes, in such a scenario, RavenDB would be vulnerable. But so would pretty much everything else. For example, MongoDB itself, even though it isn’t using OpenSSL for authentication, would also be vulnerable to such a bug in OpenSSL.

The good thing about OpenSSL’s Heartbleed bug is that it shined a huge spotlight on such bugs, and it means that a lot of time, money, and effort has been dedicated to rooting out similar issues, to the point where trust in OpenSSL has been restored.

Summary

One of the key decisions that we made when we built RavenDB was to look at how we could use the underlying (battle-tested) infrastructure to do things for us.

For security purposes, that means we have reduced the risk of vulnerabilities. A bug in RavenDB code isn’t a security vulnerability, you have to target the (much more closely scrutinized) infrastructure to actually get to a vulnerable state. That is part of our Zero Trust policy.

RavenDB has a far simpler security footprint, we use the enterprise-level TLS & X.509 for authentication instead of implementing six different protocols (and carrying the liability of each). This both simplifies the process of setting up RavenDB securely and reduces the effort required to achieve proper security compliance.

You cannot underestimate the power of checking the “X.509 client authentication” box and dropping whole sections of the security audit when deploying a new system.

PropertySphere bot: understanding images

Fri, 26 Dec 2025 12:00:00 GMT

In the previous post, I talked about the PropertySphere Telegram bot (you can also watch the full video here). In this post, I want to show how we can make it even smarter. Take a look at the following chat screenshot:

What is actually going on here? This small interaction showcases a number of RavenDB features, all at once. Let’s first focus on how Telegram hands us images. This is done using Photoor Document messages (depending on exactly how you send the message to Telegram).

The following code shows how we receive and store a photo from Telegram:

// Download the largest version of the photo from Telegram:
var ms = new MemoryStream();
var fileId = message.Photo.MaxBy(ps => ps.FileSize).FileId;
var file = await botClient.GetInfoAndDownloadFile(fileId, ms, cancellationToken);

// Create a Photo document to store metadata:
var photo = new Photo
{
    ConversationId = GetConversationId(chatId),
    Id = "photos/" + Guid.NewGuid().ToString("N"),
    RenterId = renter.Id,
    Caption = message.Caption ?? message.Text
};

// Store the image as an attachment on the document:
await session.StoreAsync(photo, cancellationToken);
ms.Position = 0;
session.Advanced.Attachments.Store(photo, "image.jpg", ms);
await session.SaveChangesAsync(cancellationToken);

// Notify the user that we're processing the image:
await botClient.SendMessage(
chatId,
       "Looking at the photo you sent..., may take me a moment...",
       cancellationToken
);

A Photo message in Telegram may contain multiple versions of the image in various resolutions. Here I’m simply selecting the best one by file size, downloading the image from Telegram’s servers to a memory stream, then I create a Photo document and add the image stream to it as an attachment.

We also tell the client to wait while we process the image, but there is no further code that does anything with it.

Gen AI & Attachment processing

We use a Gen AI task to actually process the image, handling it in the background since it may take a while and we want to keep the chat with the user open. That said, if you look at the actual screenshots, the entire conversation took under a minute.

Here is the actual Gen AI task definition for processing these photos:

var genAiTask = new GenAiConfiguration
{
    Name = "Image Description Generator",
    Identifier = TaskIdentifier,
    Collection = "Photos",
    Prompt = """
        You are an AI Assistant looking at photos from renters in 
        rental property management, usually about some issue they have. 
        Your task is to generate a concise and accurate description of what 
        is depicted in the photo provided, so maintenance can help them.
        """,


    // Expected structure of the model's response:
    SampleObject = """
        {
            "Description": "Description of the image"
        }
        """,


    // Apply the generated description to the document:
    UpdateScript = "this.Description = $output.Description;",


    // Pass the caption and image to the model for processing:
    GenAiTransformation = new GenAiTransformation
    {
        Script = """
            ai.genContext({
                Caption: this.Caption
            }).withJpeg(loadAttachment("image.jpg"));
            """
    },
    ConnectionStringName = "Property Management AI Model"
};

What we are doing here is asking RavenDB to send the caption and image contents from each document in the Photos collection to the AI model, along with the given prompt. Then we ask it to explain in detail what is in the picture.

Here is an example of the results of this task after it completed. For reference, here is the full description of the image from the model:

A leaking metal pipe under a sink is dripping water into a bucket. There is water and stains on the wooden surface beneath the pipe, indicating ongoing leakage and potential water damage.

What model is required for this?

I’m using the gpt-4.1-mini model here; there is no need for anything beyond that. It is a multimodal model capable of handling both text and images, so it works great for our needs.
You can read more about processing attachments with RavenDB’s Gen AI here.

We still need to close the loop, of course. The Gen AI task that processes the images is actually running in the background. How do we get the output of that from the database and into the chat?

To process that, we create a RavenDB Subscription to the Photos collection, which looks like this:

store.Subscriptions.Create(new SubscriptionCreationOptions
{
    Name = SubscriptionName,
    Query = """
        from "Photos" 
        where Description != null
        """
});

This subscription is called by RavenDB whenever a document in the Photos collection is created or updated with the Description having a value. In other words, this will be triggered when the GenAI task updates the photo after it runs.

The actual handling of the subscription is done using the following code:

_documentStore.Subscriptions.GetSubscriptionWorker<Photo>("After Photos Analysis")
    .Run(async batch =>
    {
        using var session = batch.OpenAsyncSession();
        foreach (var item in batch.Items)
        {
            var renter = await session.LoadAsync<Renter>(
item.Result.RenterId!);
            await ProcessMessageAsync(_botClient, renter.TelegramChatId!,
                $"Uploaded an image with caption: {item.Result.Caption}\r\n" +
                $"Image description: {item.Result.Description}.",
                cancellationToken);
        }
    });

In other words, we run over the items in the subscription batch, and for each one, we emit a “fake” message as if it were sent by the user to the Telegram bot. Note that we aren’t invoking the RavenDB conversation directly, but instead reusing the Telegram message handling logic. This way, the reply from the model will go directly back into the users' chat.

You can see how that works in the screenshot above. It looks like the model looked at the image, and then it acted. In this case, it acted by creating a service request. We previously looked at charging a credit card, and now let’s see how we handle creating a service request by the model.

The AI Agent is defined with a CreateServiceRequest action, which looks like this:

Actions = [
    new AiAgentToolAction
    {
        Name = "CreateServiceRequest",
        Description = "Create a new service request for the renter's unit",
        ParametersSampleObject = JsonConvert.SerializeObject(
            new CreateServiceRequestArgs
            {
                    Type =         """
Maintenance | Repair | Plumbing | Electrical | 
HVAC | Appliance | Community | Neighbors | Other
""",
            Description =         """
Detailed description of the issue with all 
relevant context
"""
                })
    },
]

As a reminder, this is the description of the action that the model can invoke. Its actual handling is done when we create the conversation, like so:

conversation.Handle<PropertyAgent.CreateServiceRequestArgs>(
"CreateServiceRequest", 
async args =>
{
    using var session = _documentStore.OpenAsyncSession();
    var unitId = renterUnits.FirstOrDefault();
    var propertyId = unitId?.Substring(0, unitId.LastIndexOf('/'));


    var serviceRequest = new ServiceRequest
    {
        RenterId = renter.Id!,
        UnitId = unitId,
        Type = args.Type,
        Description = args.Description,
        Status = "Open",
        OpenedAt = DateTime.UtcNow,
        PropertyId = propertyId
    };


    await session.StoreAsync(serviceRequest);
    await session.SaveChangesAsync();


    return $"Service request created ID `{serviceRequest.Id}` for your unit.";
});

In this case, there isn’t really much to do here, but hopefully this conveys the kind of code this allows you to write.

Summary

The PropertySphere sample application and its Telegram bot are interesting, mostly because of everything that isn’t here. We have a bot that has a pretty complex set of behaviors, but there isn’t a lot of complexity for us to deal with.

This behavior is emergent from the capabilities we entrusted to the model, and the kind of capabilities we give it. At the same time, I’m not trusting the model, but verifying that what it does is always within the scope of the user’s capabilities.

Extending what we have here to allow additional capabilities is easy. Consider adding the ability to get invoices directly from the Telegram interface, a great exercise in extending what you can do with the sample app.

There is also the full video where I walk you through all aspects of the sample application, and as always, we’d love to talk to you on Discord or in our GitHub discussions.

PropertySphere's intelligent Telegram bot

Mon, 22 Dec 2025 12:00:00 GMT

In the previous post, I introduced the PropertySphere sample application (you can also watch the video introducing it here). In this post, I want to go over how we build a Telegram bot for this application, so Renters can communicate with the application, check their status, raise issues, and even pay their bills.

I’m using Telegram here because the process of creating a new bot is trivial, the API is really fun to work with, and it takes very little effort.

Compare that to something like WhatsApp, where just the process for creating a bot is a PITA.

Without further ado, let’s look at what the Telegram bot looks like:

There are a bunch of interesting things that you can see in the screenshot. We communicate with the bot on the other end using natural text. There aren't a lot of screens / options that you have to go through, it is just natural mannerism.

The process is pretty streamlined from the perspective of the user. What does that look like from the implementation perspective? A lot of the time, that kind of interface involves… big amount of complexity in the backend.

Here is what I usually think when I consider those demos:

In our example, we can implement all of this in about 250 lines of code. The magic behind it is the fact that we can rely on RavenDB’s AI Agents feature to do most of the heavy lifting for us.

Inside RavenDB, this is defined as follows:

For this post, however, we’ll look at how we actually built this AI-powered Telegram bot. The full code is here if you want to browse through it.

What model is used here?

It’s worth mentioning that I’m not using anything fancy, the agent is using baseline gpt-4.1-mini for the demo. There is no need for training or customization, the way we create the agent already takes care of that.

Here is the overall agent definition:

store.AI.CreateAgent(
    new AiAgentConfiguration
    {
        Name = "Property Assistant",
        Identifier = "property-agent",
        ConnectionStringName = "Property Management AI Model",
        SystemPrompt = """
            You are a property management assistant for renters.
            ... redacted ...
            Do NOT discuss non-property topics. 
            """,
        Parameters = [
            // Visible to the model:
            new AiAgentParameter("currentDate", 
"Current date in yyyy-MM-dd format"),
            // Agent scope only, not visible to the model directly
            new AiAgentParameter("renterId", 
"Renter ID; answer only for this renter", sendToModel: false),
            new AiAgentParameter("renterUnits", 
"List of unit IDs occupied by the renter", sendToModel: false),
        ],
        SampleObject = JsonConvert.SerializeObject(new Reply
        {
            Answer = "Detailed answer to query (markdown syntax)",
            Followups = ["Likely follow-ups"],
        }),
        // redacted
    });

The code above will create an agent with the given prompt. It turns out that a lot of work actually goes into that prompt to explain to the AI model exactly what its role is, what it is meant to do, etc.

I reproduced the entire prompt below so you can read it more easily, but take into account that you’ll likely tweak it a lot, and that it is usually much longer than what we have here (although what we have below is quite functional, as you can see from the screenshots).

The agent’s prompt

You are a property management assistant for renters.
Provide information about rent, utilities, debts, service requests, and property details.
Be professional, helpful, and responsive to renters’ needs.
You can answer in Markdown format. Make sure to use ticks (`) whenever you discuss identifiers.
Do not suggest actions that are not explicitly allowed by the tools available to you.
Do NOT discuss non-property topics. Answer only for the current renter.
When discussing amounts, always format them as currency with 2 decimal places.

The way RavenDB deals with AI Agents, we define two very important aspects of them. First, we have the parameters, which define the scope of the system. In this case, you can see that we pass the currentDate, as well as provide the renterId and renterUnits that this agent is going to deal with.

We expose the current date to the model, but not the renter ID or the units that define the scope (we’ll touch on that in a bit). The model needs the current date so it will understand when it is running and have context for things like “last month”. But we don’t need to give it the IDs, they have no meaning and are instead used to define the scope of a particular conversation with the model.

The sample object we use defines the structure of the reply that we require the model to give us. In this case, we want to get a textual message from the model in Markdown format, as well as a separate array of likely follow-ups that we can provide to the user.

In order to do its job, the agent needs to be able to access the system. RavenDB handles that by letting you define queries that the model can ask the agent to execute when it needs more information. Here are some of them:

Queries = [
    new AiAgentToolQuery
    {
        Name = "GetRenterInfo",
        Description = "Retrieve renter profile details",
        Query = "from Renters where id() = $renterId",
        ParametersSampleObject = "{}",
        Options = new AiAgentToolQueryOptions
        {
            AllowModelQueries = false,
            AddToInitialContext = true
        }
    },
     new AiAgentToolQuery
    {
        Name = "GetOutstandingDebts",
        Description = "Retrieve renter's outstanding debts (unpaid balances)",
        Query = """
            from index 'DebtItems/Outstanding'
            where RenterIds in ($renterId) and AmountOutstanding > 0
            order by DueDate asc
            limit 10
            """,
        ParametersSampleObject = "{}"
    },
    new AiAgentToolQuery
    {
        Name = "GetUtilityUsage",
        Description = """
Retrieve utility usage for renter's unit within a date 
range (for calculating bills)
""",
        Query = """
            from 'Units'
            where id() in ($renterUnits)
            select 
                timeseries(from 'Power' 
between $startDate and $endDate 
group by 1d 
select sum()),
                timeseries(from 'Water' 
between $startDate and $endDate 
group by 1d 
select sum())
            """,
        ParametersSampleObject = 
"""
{
"startDate": "yyyy-MM-dd", 
"endDate": "yyyy-MM-dd"
}
"""
    },
}]

The first query in the previous snippet, GetRenterInfo, is interesting. You can see that it is marked as: AllowModelQueries = false, AddToInitialContext = true. What does that mean?

It means that as part of creating a new conversation with the model, we are going to run the query to get all the renter’s details and add that to the initial context we send to the model. That allows us to provide the model with the information it will likely need upfront.

Note that we use the $renterId and $renterUnits parameters in the queries. While they aren’t exposed directly to the model, they affect what information the model can see. This is a good thing, since it means we place guardrails very early on. The model simply cannot see any information that is out of scope for it.

The model can ask for additional information when it needs to…

An important observation about the design of AI agents with RavenDB: note that we provided the model with a bunch of potential queries that it can run. GetRenterInfo is run at the beginning, since it gives us the initial context, but the rest are left for the judgment of the model.

The model can decide what queries it needs to run in order to answer the user’s questions, and it does so of its own accord. This decision means that once you have defined the set of queries and operations that the model can run, you are mostly done. The AI is smart enough to figure out what to do and then act according to your data.

Here is an example of what this looks like from the backend:

Here you can see that the user asked about their utilities, the model then ran the appropriate query and formulated an answer for the user.

The follow-ups UX pattern

You might have noticed that we asked the model for follow-up questions that the user may want to ask. This is a hidden way to guide the user toward the set of operations that the model supports.
The model will generate the follow-ups based on its own capabilities (queries and actions that it knows it can run), so this is a pretty simple way to “tell” that to the user without being obnoxious about it.

Let’s look at how things work when we actually use this to build the bot, then come back to the rest of the agent’s definition.

Plugging the model into Telegram

We looked at the agent’s definition so far - let’s see how we actually use that. The Telegram’s API is really nice, basically boiling down to:

_botClient = new TelegramBotClient(botSecretToken);
_botClient.StartReceiving(
    HandleUpdateAsync,
    HandleErrorAsync,
    new ReceiverOptions
    {
        AllowedUpdates = [
            UpdateType.Message, 
            UpdateType.CallbackQuery 
            ]
    },
    _cts.Token
);


async Task HandleUpdateAsync(ITelegramBotClient botClient, 
Update update, CancellationToken cancellationToken)
{
    switch (update)
    {
        case { Message: { Text: { } messageText } message }:
            await ProcessMessageAsync(botClient, 
message.Chat.Id.ToString(), 
messageText, 
cancellationToken);
            break;
    }
}

And then the Telegram API will call the HandleUpdateAsync method when there is a new message to the bot. Note that you may actually get multiple (concurrent messages), maybe from different chats, at the same time.

We’ll focus on the process message function, where we start by checking exactly who we are talking to:

async Task ProcessMessageAsync(ITelegramBotClient botClient, 
string chatId, string messageText, CancellationToken cancellationToken)
{
    using var session = _documentStore.OpenAsyncSession();


    var renter = await session.Query<Renter>()
        .FirstOrDefaultAsync(r => r.TelegramChatId == chatId,
 cancellationToken);


    if (renter == null)
    {
        await botClient.SendMessage(chatId,
            "Sorry, your Telegram account is not linked to a renter profile.",
            cancellationToken: cancellationToken
        );
        return;
    }
    var conversationId = $"chats/{chatId}/{DateTime.Today:yyyy-MM-dd}";
    // more code in the next snippet
}

Telegram uses the term chat ID in their API, but it is what I would call the renter’s ID. When we register renters, we also record their Telegram chat ID, which means that when we get a message from a user, we can check whether they are a valid renter in our system. If not, we fail early and are done.

If they are, this is where things start to get interesting. Look at the conversation ID that we generated in the last line. RavenDB uses the notion of a conversation with the agent to hold state. The conversation we create here means that the bot will use the same conversation with the user for the same day.

Another way to do that would be to keep the same conversation ID open for the same user. Since RavenDB will automatically handle summarizing and trimming the conversation, either option is fine and mostly depends on your scenario.

The next stage is to create the actual conversation. To do that, we need to provide the model with the right context it is looking for:

var renterUnits = await session.Query<Lease>()
    .Where(l => l.RenterIds.Contains(renter.Id!))
    .Select(l => l.UnitId)
    .ToListAsync(cts);


var conversation = _documentStore.AI.Conversation("property-agent",
    conversationId,
    new AiConversationCreationOptions
    {
        Parameters = new Dictionary<string, object?>
        {
            ["renterId"] = renter.Id,
            ["renterUnits"] = renterUnits,
            ["currentDate"] = DateTime.Today.ToString("yyyy-MM-dd")
        }
    });

You can see that we pass the renter ID and the relevant units for the renter to the model. Those form the creation parameters for the conversation and cannot be changed. That is one of the reasons why you may want to have a different conversation per day, to get the updated values if they changed.

With that done, we can send the results back to the model and then to the user, like so:

var result = await conversation.RunAsync<PropertyAgent.Reply>(cts);


var replyMarkup = new ReplyKeyboardMarkup(result.Answer.Followups
    .Select(text => new KeyboardButton(text))
    .ToArray())
    {
        ResizeKeyboard = true,
        OneTimeKeyboard = true
    };


await botClient.SendMessage(
    chatId,
    result.Answer.Answer,
    replyMarkup: replyMarkup,
    cancellationToken: cts);

The RunAsync() method handles the entire interaction with the model, and most of the code is just dealing with the reply markup for Telegram.

If you look closely at the chat screenshot above, you can see that we aren’t just asking the model questions, we get the bot to perform actions. For example, paying the rent. Here is what this looks like:

How does this work?

Paying the rent through the bot

When we looked at the agent, we saw that we exposed some queries that the agent can run. But that isn’t the complete picture, we also give the model the ability to run actions. Here is what this looks like from the agent’s definition side:

Actions = [
    new AiAgentToolAction
    {
        Name = "ChargeCard",
        Description = """
Record a payment for one or more outstanding debts. The 
renter can pay multiple debt items in a single transaction. 
Can pay using any stored card on file.
""",
        ParametersSampleObject = JsonConvert.SerializeObject(new ChargeCardArgs
        {
            DebtItemIds = ["debtitems/1-A", "debtitems/2-A"],
            PaymentMethod = "Card",
            Card = "Last 4 digits of the card"
        })
    }
]

The idea here is that we expose to the model the kinds of actions it can request, and we specify what parameters it should pass to them, etc. What we are not doing here is giving the model control over actually running any code or modifying any data.

Instead, when the model needs to charge a card, it will have to call your code and go through validation, business logic, and authorization. Here is what this looks like on the other side. When we create a conversation, we specify handlers for all the actions we need to take, like so:

conversation.Handle<PropertyAgent.ChargeCardArgs>("ChargeCard", async args =>
{
    using var paySession = _documentStore.OpenAsyncSession();


    var renterWithCard = await paySession.LoadAsync<Renter>(renter.Id!, cts);
    var card = renterWithCard?.CreditCards
.FirstOrDefault(c => c.Last4Digits == args.Card);


    if (card == null)
    {
        throw new InvalidOperationException(
$"Card ending in {args.Card} not found in your profile.");
    }


    var totalPaid = await PaymentService.CreatePaymentForDebtsWithCardAsync(
        paySession,
        renter.Id!,
        args.DebtItemIds,
        card,
        args.PaymentMethod,
        cts);


    return $"Charged {totalPaid:C2} to {card.Type}" +
    $" ending in {card.Last4Digits}.";
});

Note that we do some basic validation, then we call the CreatePaymentForDebtsWithCardAsync()method to perform the actual operation. It is also fun that we can just return a message string to give the model an idea about what the result of the action is.

Inside CreatePaymentForDebtsWithCardAsync(),we also verify that the debts we are asked to pay are associated with the current renter; we may have to apply additional logic, etc. The concept is that we assume the model is not to be trusted, so we need to carefully validate the input and use our code to verify that everything is fine.

Summary

This post has gone on for quite a while, so I think we’ll stop here. As a reminder, the PropertySphere sample application code is available. And if you are one of those who prefer videos to text, you can watch the video here.

In the next post, I’m going to show you how we can make the bot even smarter by adding visual recognition to the mix.

PropertySphere sample application

Fri, 19 Dec 2025 12:00:00 GMT

This post introduces the PropertySphere sample application. I’m going to talk about some aspects of the sample application in this post, then in the next one, we will introduce AI into the mix.

You can also watch me walk through the entire application in this video.

This is based on a real-world scenario from a customer. One of the nicest things about AI being so easy to use is that I can generate throwaway code for a conversation with a customer that is actually a full-blown application.

The full code for the sample application is available on GitHub.

Here is the application dashboard, so you can get some idea about what this is all about:

The idea is that you have Properties (apartment buildings), which have Units (apartments), which you then Lease to Renters. Note the capitalized words in the last sentence, those are the key domain entities that we work with.

Note that this dashboard shows quite a lot of data from many different places in the system. The map defines which properties we are looking at. It’s not just a static map, it is interactive. You can zoom in on a region to apply a spatial filter to the data in the dashboard.

Let’s take a closer look at what we are doing here. I’m primarily a backend guy, so I’m ignoring what the front end is doing to focus on the actual behavior of the system.

Here is what a typical endpoint will return for the dashboard:

[HttpGet("status/{status}")]
public IActionResult GetByStatus(string status, [FromQuery] string? boundsWkt)
{
    var docQuery = _session
.Query<ServiceRequests_ByStatusAndLocation.Result,
 ServiceRequests_ByStatusAndLocation>()
        .Where(x => x.Status == status)
        .OrderByDescending(x => x.OpenedAt)
        .Take(10);


    if (!string.IsNullOrWhiteSpace(boundsWkt))
    {
        docQuery = docQuery.Spatial(
x => x.Location, spatial => spatial.Within(boundsWkt));
    }


    var results = docQuery.Select(x => new
    {
        x.Id,
        x.Status,
        x.OpenedAt,
        x.UnitId,
        x.PropertyId,
        x.Type,
        x.Description,
        PropertyName = RavenQuery.Load<Property>(x.PropertyId).Name,
        UnitNumber = RavenQuery.Load<Unit>(x.UnitId).UnitNumber
    }).ToList();


    return Ok(results);
}

We use a static index (we’ll see exactly why in a bit) to query for all the service requests by status and location, and then we project data from the document, including related document properties (the last two lines in the Select call).

A ServiceRequest doesn’t have a location, it gets that from its associated Property, so during indexing, we pull that from the relevant Property, like so:

Map = requests =>
    from sr in requests
    let property = LoadDocument<Property>(sr.PropertyId)
    select new Result
    {
        Id = sr.Id,
        Status = sr.Status,
        OpenedAt = sr.OpenedAt,
        UnitId = sr.UnitId,
        PropertyId = sr.PropertyId,
        Type = sr.Type,
        Description = sr.Description,
        Location =  CreateSpatialField(property.Latitude, property.Longitude),
    };

You can see how we load the related Property and then index its location for the spatial query (last line).

You can see more interesting features when you drill down to the Unit page, where both its current status and its utility usage are displayed. That is handled using RavenDB’s time series feature, and then projected to a nice view on the frontend:

In the backend, this is handled using the following action call:

[HttpGet("unit/{*unitId}")]
public IActionResult GetUtilityUsage(string unitId, 
[FromQuery] DateTime? from, [FromQuery] DateTime? to)
{
var unit = _session.Load<Unit>(unitId);
if (unit == null)
    return NotFound("Unit not found");


var fromDate = from ?? DateTime.Today.AddMonths(-3);
var toDate = to ?? DateTime.Today;


var result = _session.Query<Unit>()
    .Where(u => u.Id == unitId)
    .Select(u => new
    {
        PowerUsage = RavenQuery.TimeSeries(u, "Power")
            .Where(ts => ts.Timestamp >= fromDate && ts.Timestamp <= toDate)
            .GroupBy(g => g.Hours(1))
            .Select(g => g.Sum())
            .ToList(),
        WaterUsage = RavenQuery.TimeSeries(u, "Water")
            .Where(ts => ts.Timestamp >= fromDate && ts.Timestamp <= toDate)
            .GroupBy(g => g.Hours(1))
            .Select(g => g.Sum())
            .ToList()
    })
    .FirstOrDefault();


return Ok(new
{
    UnitId = unitId,
    UnitNumber = unit.UnitNumber,
    From = fromDate,
    To = toDate,
    PowerUsage = result?.PowerUsage?.Results?
.Select(r => new UsageDataPoint
    {
        Timestamp = r.From,
        Value = r.Sum[0],
    }).ToList() ?? new List<UsageDataPoint>(),
    WaterUsage = result?.WaterUsage?.Results?
.Select(r => new UsageDataPoint
    {
        Timestamp = r.From,
        Value = r.Sum[0],
    }).ToList() ?? new List<UsageDataPoint>()
});

As you can see, we run a single query to fetch data from multiple time series, which allows us to render this page.

By now, I think you have a pretty good grasp of what the application is about. So get ready for the next post, where I will talk about how to add AI capabilities to the mix.

RavenDB Kubernetes Operator

Mon, 15 Dec 2025 12:00:00 GMT

I’m happy to announce the official release of the RavenDB Kubernetes Operator.

As organizations use Kubernetes for more and more parts of their infrastructure, the complexity of deploying databases in such an environment is quite a challenge. For RavenDB, you need to handle certificates, persistence, and upgrades, and it is easy for that to become a bottleneck. This release bridges the gap between RavenDB’s ease of use and the declarative power of Kubernetes.

If you are new to the concept, think of an operator as software that acts like a Site Reliability Engineer (SRE). Kubernetes is excellent at managing stateless applications, but databases require specific knowledge to manage correctly (e.g., "Don't upgrade all nodes at once" or "Ensure the leader is stable before restarting").

The RavenDB Operator extends the Kubernetes API. It allows you to define what you want your cluster to look like (the "Manifest"), and the Operator works tirelessly in the background to make sure your infrastructure matches that state.

Why This Matters

Previously, deploying a secure, clustered RavenDB instance on K8s required manual configuration of StatefulSets, Services, and complex TLS certificate chains.

With the RavenDB Kubernetes Operator, everything is driven by a single custom resource: RavenDBCluster. You provide the specs, and the Operator handles the heavy lifting, ensuring your deployments are fully reproducible, secure, and declarative.

Here is what the Operator brings to the table:

Automated Security & Certificate Management: Whether you are using Let’s Encrypt or Self-Signed certificates, the Operator handles bootstrapping, distribution, and rotation.For the Operator’s own webhook certificate, the Operator uses cert-manager behind the scenes, since that is not exposed externally.
Safe Rolling Upgrades: Database upgrades can be scary. The Operator orchestrates upgrades node-by-node, using safety gates to ensure the cluster is healthy and data is safe before moving to the next node. If a gate fails, the upgrade stops automatically.
Flexible External Access: Exposing a database outside K8s is often a networking headache. We’ve added dedicated support for AWS NLB, Azure Load Balancer, HAProxy, Traefik, and NGINX, giving you production-ready access strategies out of the box.
Storage Orchestration: Declarative control over your data, logs, and audit volumes, supporting local paths, AWS EBS, and Azure Disks.
One-Click Deploy: Using our official Helm chart, you can spin up a fully operational cluster in minutes.

The Operator is available now via Helm and works on EKS, AKS, Kind, Minikube, and Kubeadm clusters.

ArtifactHub (Helm Chart):Get the Chart
GitHub Repository:View Source & Examples
Quickstart Guide:Read the Docs

We look forward to seeing what you build with RavenDB on Kubernetes!

Implementing Agentic Reminders in RavenDB

Mon, 08 Dec 2025 12:00:00 GMT

A really interesting problem for developers building agentic systems is moving away from chatting with the AI model. For example, consider the following conversation:

This is a pretty simple scenario where we need to actually step out of the chat and do something else. This seems like an obvious request, right? But it turns out to be a bit complex to build.

The reason for that is simple. AI models don’t actually behave like you would expect them to if your usage is primarily as a chat interface. Here is a typical invocation of a model in code:

class MessageTuple(NamedTuple):
    role: str
    content: str


def call_model(
    message_history: List[MessageTuple],
    tools: List[Callable] = None
):
   pass # redacted

In other words, it is the responsibility of the caller to keep track of the conversation and send the entire conversation to the agent on each round. Here is what this looks like in code:

conversation_history = [
    {
        "role": "user",
        "content": "When do I get my anniversary gift?"
    },
    {
        "role": "agent",
        "content": "Based on our records, your two-year anniversary is in three days. This milestone means you're eligible for a gift card as part of our company's recognition program.\nOur policy awards a $100 gift card for each year of service. Since you've completed two years, a $200 gift card will be sent to you via SMS on October 1, 2025."
    },
    {
        "role": "user",
        "content": "Remind me to double check I got that in a week"
    }
]

Let’s assume that we have a tool call for setting up reminders for users. In RavenDB, this looks like the screenshot below (more on agentic actions in RavenDB here):

And in the backend, we have the following code:

conversation.Handle<CreateReminderArgs>("CreateReminder", async (args) =>
{
    using var session = _documentStore.OpenAsyncSession();
    var at = DateTime.Parse(args.at);
    var reminder = new Reminder
    {
        EmployeeId = request.EmployeeId,
        ConversationId = conversation.Id,
        Message = args.msg,
    };
    await session.StoreAsync(reminder);
    session.Advanced.GetMetadataFor(reminder)["@refresh"] = at;
    await session.SaveChangesAsync();


    return $"Reminder set for {at} {reminder.Id}";
});

This code uses several of RavenDB’s features to perform its task. First we have the conversation handler, which is the backend handling for the tool call we just saw. Next we have the use of the @refresh feature of RavenDB. I recently posted about how you can use this feature for scheduling.

In short, we set up a RavenDB Subscription Task to be called when those reminders should be raised. Here is what the subscription looks like:

<pre class='line-numbers language-javascript'><code class='line-numbers language-javascript'>from Reminders as r where r.'@metadata'.'@refresh' != null

And here is the client code to actually handle it:

<pre class='line-numbers language-javascript'><code class='line-numbers language-javascript'>async Task HandleReminder(Reminder reminder) { var conversation = _documentStore.AI.Conversation( agentId: "smartest-agent", reminder.ConversationId, creationOptions: null ); conversation.AddArtificialActionWithResponse( "GetRaisedReminders", reminder); var result = await conversation.RunAsync(); await MessageUser(conversation, result); }

The question now is, what should we do with the reminder?

Going back to the top of this post, we know that we need to add the reminder to the conversation. The problem is that this isn’t part of the actual model of the conversation. This is neither a user prompt nor a model answer. How do we deal with this?

We use a really elegant approach here: we inject an artificial tool call into the conversation history. This makes the model think that it checked for reminders and received one in return, even though this happened outside the chat. This lets the agent respond naturally, as if the reminder were part of the ongoing conversation, preserving the full context.

Finally, since we’re not actively chatting with the user at this point, we need to send a message prompting them to check back on the conversation with the model.

Summary

This is a high-level post, meant specifically to give you some ideas about how you can take your agentic systems to a higher level than a simple chat with the model. The reminder example is a pretty straightforward example, but a truly powerful one. It transforms a simple chat into a much more complex interaction model with the AI.

RavenDB’s unique approach of "inserting" a tool call back into the conversation history effectively tells the AI model, "I've checked for reminders and found a reminder for this user." This allows the agent to handle the reminder within the context of the original conversation, rather than initiating a new one. It also allows the agent to maintain a single, coherent conversational thread with the user, even when the system needs to perform background tasks and re-engage with them later.

You can also use the same infrastructure to create a new conversation, if that makes sense in your domain, and use the previous conversation as “background material”, so to speak. There is a wide variety of options available to fit your exact scenario.

Recording: From CRUD TO AI – building an intelligent Telegram bot in < 200 lines of code with RavenDB

Tue, 02 Dec 2025 12:00:00 GMT

Want to see how modern applications handle complexity, scale, and cutting-edge features without becoming unmanageable? In this deep-dive webinar, we move From CRUD to AI Agents, showcasing how RavenDB, a high-performance document database, simplifies the development of a complex Property Management application.

Using multi-staged actions with AI Agents to reduce costs & time

Mon, 17 Nov 2025 12:00:00 GMT

When building AI Agents, one of the challenges you have to deal with is the sheer amount of data that the agent may need to go through. A natural way to deal with that is not to hand the information directly to the model, but rather allow it to query for the information as it sees fit.

For example, in the case of a human resource assistant, we may want to expose the employer’s policies to the agent, so it can answer questions such as “What is the required holiday request time?”.

We can do that easily enough using the following agent-query mechanism:

If the agent needs to answer a question about a policy, it can use this tool to get the policies and find out what the answer is.

That works if you are a mom & pop shop, but what happens if you happen to be a big organization, with policies on everything from requesting time off to bringing your own device to modern slavery prohibition? Calling this tool is going to give all those policies to the model?

That is going to be incredibly expensive, since you have to burn through a lot of tokens that are simply not relevant to the problem at hand.

The next step is not to return all of the policies and filter them. We can do that using vector search and utilize the model’s understanding of the data to help us find exactly what we want.

That is much better, but a search for “confidentiality contract” will get you the Non-Disclosure Agreement as well as the processes for hiring a new employee when their current employer isn’t aware they are looking, etc.

That can still be a lot of text to go through. It isn’t as much as everything, but still a pretty heavy weight.

A nice alternative to this is to break it into two separate operations, as you can see below:

The model will first run the FindPolicies query to get the list of potential policies. It can then decide, based on their titles, which ones it is actually interested in reading the full text of.

You need to perform two tool calls in this case, but it actually ends up being both faster and cheaper in the end.

This is a surprisingly elegant solution, because it matches roughly how people think. No one is going to read a dozen books cover to cover to answer a question. We continuously narrow our scope until we find enough information to answer.

This approach gives your AI model the same capability to narrowly target the information it needs to answer the user’s query efficiently and quickly.

Reducing AI context load using actions

Fri, 14 Nov 2025 12:00:00 GMT

When using an AI model, one of the things that you need to pay attention to is the number of tokens you send to the model. They literally cost you money, so you have to balance the amount of data you send to the model against how much of it is relevant to what you want it to do.

That is especially important when you are building generic agents, which may be assigned a bunch of different tasks. The classic example is the human resources assistant, which may be tasked with checking your vacation days balance or called upon to get the current number of overtime hours that an employee has worked this month.

Let’s assume that we want to provide the model with a bit of context. We want to give the model all the recent HR tickets by the current employee. These can range from onboarding tasks to filling out the yearly evaluation, etc.

That sounds like it can give the model a big hand in understanding the state of the employee and what they want. Of course, that assumes the user is going to ask a question related to those issues.

What if they ask about the date of the next bank holiday? If we just unconditionally fed all the data to the model preemptively, that would be:

Quite confusing to the model, since it will have to sift through a lot of irrelevant data.
Pretty expensive, since we’re going to send a lot of data (and pay for it) to the model, which then has to ignore it.
Compounding effect as the user & the model keep the conversation going, with all this unneeded information weighing everything down.

A nice trick that can really help is to not expose the data directly, but rather provide it to the model as a set of actions it can invoke. In other words, when defining the agent, I don’t bother providing it with all the data it needs.

Rather, I provide the model a way to access the data. Here is what this looks like in RavenDB:

The agent is provided with a bunch of queries that it can call to find out various interesting details about the current employee. The end result is that the model will invoke those queries to get just the information it wants.

The overall number of tokens that we are going to consume will be greatly reduced, while the ability of the model to actually access relevant information is enhanced. We don’t need to go through stuff we don’t care about, after all.

This approach gives you a very focused model for the task at hand, and it is easy to extend the agent with additional information-retrieval capabilities.

Using AI Agents parameters outside of the model's scope

Wed, 12 Nov 2025 12:00:00 GMT

Building an AI Agent in RavenDB is very much like defining a class, you define all the things that it can do, the initial prompt to the AI model, and you specify which parameters the agent requires. Like a class, you can create an instance of an AI agent by starting a new conversation with it. Each conversation is a separate instance of the agent, with different parameters, an initial user prompt, and its own history.

Here is a simple example of a non-trivial agent. For the purpose of this post, I want to focus on the parameters that we pass to the model.

var agent = new AiAgentConfiguration(
"shopping assistant", 
config.ConnectionStringName,
"You are an AI agent of an online shop...")
{
    Parameters =
    [ 
       new AiAgentParameter("lang", 
"The language the model should respond with."),
        new AiAgentParameter("currency", "Preferred currency for the user"),
        new AiAgentParameter("customerId", null, sendToModel: false),
    ],
    Queries = [ /* redacted... */ ],
    Actions = [ /* redacted... */ ],
};

As you can see in the configuration, we define the lang and currency parameters as standard agent parameters. These are defined with a description for the model and are passed to the model when we create a new conversation.

But what about the customerId parameter? It is marked as sendToModel: false. What is the point of that? To understand this, you need to know a bit more about how RavenDB deals with the model, conversations, and memory.

Each conversation with the model is recorded using a conversation document, and part of this includes the parameters you pass to the conversation when you create it. In this case, we don’t need to pass the customerId parameter to the model; it doesn’t hold any meaning for the model and would just waste tokens.

The key is that you can query based on those parameters. For example, if you want to get all the conversations for a particular customer (to show them their conversation history), you can use the following query:

from "@conversations" 
where Parameters.customerId = $customerId

This is also very useful when you have data that you genuinely don’t want to expose to the model but still want to attach to the conversation. You can set up a query that the model may call to get the most recent orders for a customer, and RavenDB will do that (using customerId) without letting the model actually see that value.

The cost of design iteration in software engineering

Mon, 13 Oct 2025 12:00:00 GMT

I ran into this tweet from about a month ago:

dax @thdxr

programmers have a dumb chip on their shoulder that makes them try and emulate traditional engineering there is zero physical cost to iteration in software - can delete and start over, can live patch our approach should look a lot different than people who build bridges

I have to say that I would strongly disagree with this statement. Using the building example, it is obvious that moving a window in an already built house is expensive. Obviously, it is going to be cheaper to move this window during the planning phase.

The answer is that it may be cheaper, but it won’t necessarily be cheap. Let’s say that I want to move the window by 50 cm to the right. Would it be up to code? Is there any wiring that needs to be moved? Do I need to consider the placement of the air conditioning unit? What about the emergency escape? Any structural impact?

This is when we are at the blueprint stage - the equivalent of editing code on screen. And it is obvious that such changes can be really expensive. Similarly, in software, every modification demands a careful assessment of the existing system, long-term maintenance, compatibility with other components, and user expectations.This intricate balancing act is at the core of the engineering discipline.

A civil engineer designing a bridge faces tangible constraints: the physical world, regulations, budget limitations, and environmental factors like wind, weather, and earthquakes.While software designers might not grapple with physical forces, they contend with equally critical elements such as disk usage, data distribution, rules & regulations, system usability, operational procedures, and the impact of expected future changes.

Evolving an existing software system presents a substantial engineering challenge.Making significant modifications without causing the system to collapse requires careful planning and execution.The notion that one can simply "start over" or "live deploy" changes is incredibly risky.History is replete with examples of major worldwide outages stemming from seemingly simple configuration changes.A notable instance is the Google outage of June 2025, where a simple missing null check brought down significant portions of GCP. Even small alterations can have cascading and catastrophic effects.

I’m currently working on a codebase whose age is near the legal drinking age. It also has close to 1.5 million lines of code and a big team operating on it. Being able to successfully run, maintain, and extend that over time requires discipline.

In such a project, you face issues such as different versions of the software deployed in the field, backward compatibility concerns, etc. For example, I may have a better idea of how to structure the data to make a particular scenario more efficient. That would require updating the on-disk data, which is a 100% engineering challenge. We have to take into consideration physical constraints (updating a multi-TB dataset without downtime is a tough challenge).

The moment you are actually deployed, you have so many additional concerns to deal with. A good example of this may be that users are used to stuff working in a certain way. But even for software that hasn’t been deployed to production yet, the cost of change is high.

Consider the effort associated with this update to a JobApplication class:

This looks like a simple change, right? It just requires that you (partial list):

Set up database migration for the new shape of the data.
Migrate the existing data to the new format.
Update any indexes and queries on the position.
Update any endpoints and decide how to deal with backward compatibility.
Create a new user interface to match this whenever we create/edit/view the job application.
Consider any existing workflows that inherently assume that a job application is for a single position.
Can you be partially rejected? What is your status if you interviewed for one position but received an offer for another?
How does this affect the reports & dashboard?

This is a simple change, no? Just a few characters on the screen. No physical cost. But it is also a full-blown Epic Task for the project - even if we aren’t in production, have no data to migrate, or integrations to deal with.

Software engineersoperate under constraints similar to other engineers, including severe consequences for mistakes (global system failure because of a missing null check). Making changes to large, established codebases presents a significant hurdle.

The moment that you need to consider more than a single factor, whether in your code or in a bridge blueprint, there is a pretty high cost to iterations. Going back to the bridge example, the architect may have a rough idea (is it going to be a Roman-style arch bridge or a suspension bridge) and have a lot of freedom to play with various options at the start. But the moment you begin to nail things down and fill in the details, the cost of change escalates quickly.

Finally, just to be clear, I don’t think that the cost of changing software is equivalent to changing a bridge after it was built. I simply very strongly disagree that there is zero cost (or indeed, even low cost) to changing software once you are past the “rough draft” stage.

Using AI for candidate ranking with RavenDB

Fri, 10 Oct 2025 12:00:00 GMT

Hiring the right people is notoriously difficult.I have been personally involved in hiring decisions for about two decades, and it is an unpleasant process. You deal with an utterly overwhelming influx of applications, often from candidates using the “spray and pray” approach of applying to all jobs.

At one point, I got the resume of a divorce lawyer in response to a job posting for a backend engineer role. I was curious enough to follow up on that, and no, that lawyer didn’t want to change careers. He was interested in being a divorce lawyer. What kind of clients would want their divorce handled by a database company, I refrained from asking.

Companies often resort to expensive external agencies to sift through countless candidates.

In the age of AI and LLMs, is that still the case? This post will demonstrate how to build an intelligent candidate screening process using RavenDB and modern AI, enabling you to efficiently accept applications, match them to appropriate job postings, and make an initial go/no-go decision for your recruitment pipeline.

We’ll start our process by defining a couple of open positions:

Staff Engineer, Backend & DevOps
Senior Frontend Engineer (React/TypeScript/SaaS)

Here is what this looks like at the database level:

Now, let’s create a couple of applicants for those positions. We have James & Michael, and they look like this:

Note that we are not actually doing a lot here in terms of the data we ask the applicant to provide. We mostly gather the contact information and ask them to attach their resume. You can see the resume attachment in RavenDB Studio. In the above screenshot, it is in the right-hand Attachments pane of the document view.

Now we can use RavenDB’s new Gen AI attachments feature. I defined an OpenAI connection with gpt-4.1-mini and created a Gen AI task to read & understand the resume. I’m assuming that you’ve read my post about Gen AI in RavenDB, so I’ll skip going over the actual setup.

The key is that I’m applying the following context extraction script to the Applicants collection:

const resumePdf = loadAttachment("resume.pdf");
if(!resumePdf) return;


ai.genContext({name: this.applicantName})
    .withPdf(resumePdf);

When I test this script on James’s document, I get:

Note that we have the attachment in the bottom right - that will also be provided to the model. So we can now write the following prompt for the model:

You are an HR data parsing specialist. Your task is to analyze the provided CV/resume content (from the PDF) 
and extract the candidate's professional profile into the provided JSON schema.
In the requiredTechnologies object, every value within the arrays (languages, frameworks_libraries, etc.) must be a single, 
distinct technology or concept. Do not use slashes (/), commas, semicolons, or parentheses () to combine items within a single string. Separate combined concepts into individual strings (e.g., "Ruby/Rails" becomes "Ruby", "Rails").

We also ask the model to respond with an object matching the following sample:

{
  "location": "The primary location or if interested in remote option (e.g., Pasadena, CA or Remote)",
  "summary": "A concise overview of the candidate's history and key focus areas (e.g., Lead development of data-driven SaaS applications focusing on React, TypeScript, and Usability).",
  "coreResponsibilities": [
    "A list of the primary duties and contributions in previous roles."
  ],
  "requiredTechnologies": {
    "languages": [
      "Key programming and markup languages that the candidate has experience with."
    ],
    "frameworks_libraries": [
      "Essential UI, state management, testing, and styling libraries."
    ],
    "tools_platforms": [
      "Version control, cloud platforms, build tools, and project management systems."
    ],
    "data_storage": [
      "The database technologies the candidate is expected to work with."
    ]
  }
}

Testing this on James’s applicant document results in the following output:

I actually had to check where the model got the “LA Canada” issue. That shows up in the real resume PDF, and it is a real place. I triple-checked, because I was sure this was a hallucination at first ☺️.

The last thing we need to do is actually deal with the model’s output. We use an update script to apply the model’s output to the document. In this case, it is as simple as just storing it in the source document:

this.resume = $output;

And here is what the output looks like:

Reminder: Gen AI tasks in RavenDB use a three-stage approach:

Context extraction script - gets data (and attachment) from the source document to provide to the model.
Prompt & Schema - instructions for the model, telling it what it should do with the provided context and how it should format the output.
Update script - takes the structured output from the model and applies it back to the source document.

In our case, this process starts with the applicant uploading their CV, and then we have the Read Resume task running. This parses the PDF and puts the result in the document, which is great, but it is only part of the process.

We now have the resume contents in a structured format, but we need to evaluate the candidate’s suitability for all the positions they applied for. We are going to do that using the model again, with a new Gen AI task.

We start by defining the following context extraction script:

// wait until the resume (parsed CV) has been added to the document
if (!this.resume) return; 


for(const positionId of this.targetPosition) {
    const position = load(positionId);
    if(!position) continue;
    ai.genContext({
        position,
        positionId,
        resume: this.resume
    })
}

Note that this relies on the resume field that we created in the previous task. In other words, we set things up in such a way that we run this task after the Read Resume task, but without needing to put them in an explicit pipeline or manage their execution order.

Next, note that we output multiple contexts for the same document. Here is what this looks like for James, we have two separate contexts, one for each position James applied for:

This is important because we want to process each position and resume independently. This avoids context leakage from one position to another. It also lets us process multiple positions for the same applicant concurrently.

Now, we need to tell the model what it is supposed to do:

You are a specialized HR Matching AI. Your task is to receive two structured JSON objects — one describing a Job Position and one 
summarizing a Candidate Resume — and evaluate the suitability of the resume for the position.


Assess the overlap in jobTitle, summary, and coreResponsibilities. Does the candidate's career trajectory align with the role's needs (e.g., has matching experience required for a Senior Frontend role)?
Technical Match: Compare the technologies listed in the requiredTechnologies sections. Identify both direct matches (must-haves) and gaps (missing or weak areas). Consider substitutions such as js or ecmascript to javascript or node.js. 


Evaluate if the candidate's experience level and domain expertise (e.g., SaaS, Data Analytics, Mapping Solutions) meet or exceed the requirements.

And the output schema that we want to get from the model is:

{
  "explanation": "Provide a detailed analysis here. Start by confirming the high-level match (e.g., 'The candidate is an excellent match because...'). Detail the strongest technical overlaps (e.g., React, TypeScript, Redux, experience with BI/SaaS). Note any minor mismatches or significant overqualifications (e.g., candidate's deep experience in older technologies like ASP.NET classic is not required but demonstrates full-stack versatility).",  "isSuitable": false
}

Here I want to stop for a moment and talk about what exactly we are doing here. We could ask the model just to judge whether an applicant is suitable for a position and save a bit on the number of tokens we spend. However, getting just a yes/no response from the model is not something I recommend.

There are two primary reasons why we want the explanation field as well. First, it serves as a good check on the model itself. The order of properties matters in the output schema. We first ask the model to explain itself, then to render the verdict. That means it is going to be more focused.

The other reason is a bit more delicate. You may be required to provide an explanation to the applicant if you reject them. I won’t necessarily put this exact justification in the rejection letter to the applicant, but it is something that is quite important to retain in case you need to provide it later.

Going back to the task itself, we have the following update script:

this.suitability = this.suitability || {};
this.suitability[$input.positionId] = $output;

Here we are doing something quite interesting. We extracted the positionId at the start of this process, and we are using it to associate the output from the model with the specific position we are currently evaluating.

Note that we are actually evaluating multiple positions for the same applicant at the same time, and we need to execute this update script for each of them. So we need to ensure that we don’t overwrite previous work.

I’m not mentioning this in detail because I covered it in my previous Gen AI post, but it is important to note that we have two tasks sourced from the same document. RavenDB knows how to handle the data being modified by both tasks without triggering an infinite loop. It seems like a small thing, but it is the sort of thing that not having to worry about really simplifies the whole process.

With these two tasks, we have now set up a complete pipeline for the initial processing of applicants to open positions. As you can see here:

This sort of process allows you to integrate into your system stuff that, until recently, looked like science fiction. A pipeline like the one above is not something you could just build before, but now you can spend a few hours and have this capability ready to deploy.

Here is what the tasks look like inside RavenDB:

And the final applicant document after all of them have run is:

You can see the metadata for the two tasks (which we use to avoid going to the model again when we don’t have to), as well as the actual outputs of the model (resume, suitability fields).

A few more notes before we close this post. I chose to use two GenAI tasks here, one to read the resume and generate the structured output, and the second to actually evaluate the applicant’s suitability.

From a modeling perspective, it is easier to split this into distinct steps. You can ask the model to both read the resume and evaluate suitability in a single shot, but I find that it makes it harder to extend the system down the line.

Another reason you want to have different tasks for this is that you can use different models for each one. For example, reading the resume and extracting the structured output is something you can run on gpt-4.1-mini or gpt-5-nano, while evaluating applicant suitability can make use of a smarter model.

I’m really happy with the new RavenDB AI integration features. We got some early feedback that is really exciting, and I’m looking forward to seeing what you can do with them.

When perf optimization breaks tests in a GOOD way

Tue, 07 Oct 2025 12:00:00 GMT

You might have noticed a theme going on in RavenDB. We care a lot about performance. The problem with optimizing performance is that sometimes you have a great idea, you implement it, the performance gains are there to be had - and then a test fails… and you realize that your great idea now needs to be 10 times more complex to handle a niche edge case.

We did a lot of work around optimizing the performance of RavenDB at the lowest levels for the next major release (8.0), and we got a persistently failing test that we started to look at.

Here is the failing message:

Restore with MaxReadOpsPerSecond = 1 should take more than '11' seconds, but it took '00:00:09.9628728'

The test in question is ShouldRespect_Option_MaxReadOpsPerSec_OnRestore, part of the MaxReadOpsPerSecOptionTests suite of tests. What it tests is that we can limit how fast RavenDB can restore a database.

The reason you want to do that is to avoid consuming too many system resources when performing a big operation. For example, I may want to restore a big database, but I don’t want to consume all the IOPS on the server, because there are additional databases running on it.

At any rate, we started to get test failures on this test. And a deeper investigation revealed something quite amusing. We made the entire system more efficient. In particular, we managed to reduce the size of the buffers used significantly, so we can push more data faster. It turns out that this is enough to break the test.

The fix was to reduce the actual time that we budget as the minimum viable time. And I have to say that this is one of those pull requests that lights a warm fire in my heart.

Cryptographic documents in RavenDB

Fri, 26 Sep 2025 12:00:00 GMT

We got an interesting use case from a customer - they need to verify that documents in RavenDB have not been modified by any external party, including users with administrator credentials for the database.

This is known as the Rogue Root problem, where you have to protect yourself from potentially malicious root users. That is not an easy problem - in theory, you can safeguard yourself using various means, for example the whole premise of SELinux is based on that.

I don’t really like that approach, since I assume that if a user has (valid) root access, they also likely have physical access. In other words, they can change the operating system to bypass any hurdles in the way.

Luckily, the scenario we were presented with involved detecting changes made by an administrator, which is significantly easier. And we can also use some cryptography tools to help us handle even the case of detecting malicious tampering.

First, I’m going to show how to make this work with RavenDB, then we’ll discuss the implications of this approach for the overall security of the system.

The implementation

The RavenDB client API allows you to hook into the saving process of documents, as you can see in the code below. In this example, I’m using a user-specific ECDsa key (by calling the GetSigningKeyForUser() method).

store.OnBeforeStore += (sender, e) =>
{
    using var obj = e.Session.JsonConverter.ToBlittable(e.Entity, null);
    var date = DateTime.UtcNow.ToString("O");
    var data = Encoding.UTF8.GetBytes( e.DocumentId + date + obj);
    
    using ECDsa key = GetSigningKeyForUser(CurrentUser);
    var signData = key.SignData(data, HashAlgorithmName.SHA256);


    e.DocumentMetadata["DigitalSignature"] = new Dictionary<string, string>
    {
        ["User"] = CurrentUser,
        ["Signature"] = Convert.ToBase64String(signData),
        ["Date"] = date,
        ["PublicKey"] = key.ExportSubjectPublicKeyInfoPem()
    };
};

What you can see here is that we are using the user’s key to generate a signature that is composed of:

The document’s ID.
The current signature time.
The JSON content of the entity.

After we generate the signature, we add it to the document’s metadata. This allows us to verify that the entity is indeed valid and was signed by the proper user.

To validate this afterward, we use the following code:

bool ValidateEntity<T>(IAsyncDocumentSession session,T entity)
{
    var metadata = session.Advanced.GetMetadataFor(entity);
    var documentId = session.Advanced.GetDocumentId(entity);
    var digitalSignature = metadata.GetObject("DigitalSignature") ??
          throw new IOException("Signature is missing for " + documentId);
    var date = digitalSignature.GetString("Date");
    var user = digitalSignature.GetString("User");
    var signature = digitalSignature.GetString("Signature");
    using var key = GetPublicKeyForUser(user);
    using var obj = session.Advanced.JsonConverter.ToBlittable(entity, null);
    var data = Encoding.UTF8.GetBytes(documentId + date + obj);
    var bytes = Convert.FromBase64String(signature);
    return key.VerifyData(data, bytes, HashAlgorithmName.SHA256);
}

Note that here, too, we are using the GetPublicKeyForUser() to get the proper public key to validate the signature. We use the specified user from the metadata to get the key, and we verify the signature against the document ID, the date in the metadata, and the JSON of the entity.

We are also saving the public key of the signing user in the metadata. But we haven’t used it so far, why are we doing this?

The reason we use GetPublicKeyForUser() in the ValidateEntity() call is pretty simple: we want to get the user’s key from the same source. This assumes that the user’s key is stored in a safe location (a secure vault or a hardware key like YubiKey, etc.).

The reason we want to store the public key in the metadata is so we can verify the data on the server side. I created the following index:

from c in docs.Companies
let unverified = Crypto.Verify(c)
where unverified is not null
select new 
{ 
    Problem = unverified
}

I’m using RavenDB’s additional sources feature to add the following code to the index. This exposes the Crypto.Verify() call to the index, and the code uses the public key in the metadata (as well as the other information there) to verify that the document signature is valid.

The index code above will filter all the documents whose signature is valid, so you can easily get all the problematic documents. In other words, it is a quick way of saying: “Find me all the documents whose verification failed”. For compliance, that is quite important and usually requires going over the entire dataset to answer it.

The implications

Let’s consider the impact of such a system. We now have cryptographic verification that the document was modified by a specific user. Any tampering with the document will invalidate the digital signature (or require signing it with your key).

Combine that with RavenDB’s revisions, and you have an immutable log that you can verify using modern cryptography. No, it isn’t a blockchain, but it will put a significant roadblock in the path of anyone trying to just modify the data.

The fact that we do the signing on the client side, rather than the server, means that the server never actually has access to the signing keys (only the public keys). The server’s administrator, in the same manner, doesn’t have a way to get those signing keys and forge a document.

In other words, we solved the Rogue Root problem, and we ensured that a user cannot repudiate a document they signed. It is easy to audit the system for invalid documents (and, combined with revisions, go back to a valid one).

Escape hatch design

If you need this sort of feature for compliance only, you may want to skip the ValidateEntity() call. That would allow an administrator to manually change a document (thus invalidating the digital signature) and still have the rest of the system work. That goes against what we are trying to do, yes, but it is sometimes desirable.

That isn’t required for the normal course of operations, but it can be required for troubleshooting, for example. I’m sure you can think of a number of reasons why it would make things a lot easier to fix if you could just modify the database’s data.

For example, an Order contains a ZipCode with the value "02116" (note the leading zero), which a downstream system turns into the integer 02116. An administrator can change the value to be " 02116", with a leading space, preventing this problem (the downstream system will not convert this to a number, thus keeping the leading 0). Silly, yes - but it happens all the time.

Even though we are invalidating the digital signature, we may want to do that anyway. The index we defined would alert on this, but we can proceed with processing the order, then fix it up later. Or just make a note of this for compliance purposes.

Summary

This post walks you through building a cryptographic solution to protect document integrity within a RavenDB environment, addressing the Rogue Root problem. The core mechanism is a client-side OnBeforeStore hook that generates an ECDsa digital signature for each document. This design ensures that the private keys are never exposed on the server, preventing a database administrator from forging signatures and providing true non-repudiation.

A RavenDB index is used to automatically and asynchronously verify every document's signature against its current content. This index filters for any documents where the digital signature is valid, providing an efficient server-side audit mechanism to find all the documents with invalid signatures.

The really fun part here is that there isn’t really a lot of code or complexity involved, and you get strong cryptographic proof that your data has not been tampered with.

Recording: How To Create Powerful and Secure AI Agents with RavenDB

Mon, 22 Sep 2025 12:00:00 GMT

Unlock practical AI agents inside your database. In this live demo and deep dive, Oren Eini shows how to build real, production-ready AI agents directly in RavenDB that query your data, take actions, remember context, and stay inside strict security guardrails. You will see an agent defined in a few lines of code, connected to OpenAI or any LLM you choose, running vector search and RAG over your catalog, and safely executing business actions like “add to cart,” “find policies,” or “sign document,” all with parameters that are enforced by the database rather than trusted to the model. You will learn how RavenDB agents eliminate fragile glue code by giving the model explicit tools: data queries that return typed results and server-side actions you validate in your code.

Conversations are stored as documents, with automatic token-aware summarization to control latency and cost. The demo streams responses token by token for responsive UX, switches models without rewrites, and shows how scope parameters prevent data leaks even if the prompt is manipulated. You will also see a multi-tool HR assistant that chains tools, coordinates front end and back end, and persists state. The session closes with a look at the roadmap, including multi-agent orchestration and AI assist inside Studio.

Scheduling with RavenDB

Thu, 18 Sep 2025 12:00:00 GMT

I got a question from one of our users about how they can use RavenDB to manage scheduled tasks. Stuff like: “Send this email next Thursday” or “Cancel this reservation if the user didn’t pay within 30 minutes.”

As you can tell from the context, this is both more straightforward and more complex than the “run this every 2nd Wednesday" you’ll typically encounter when talking about scheduled jobs.

The answer for how to do that in RavenDB is pretty simple, you use the Document Refresh feature. This is a really tiny feature when you consider what it does. Given this document:

{
   "Redacted": "Details",
   "@metdata": {
      "@collection": "RoomAvailabilities",
      "@refresh": "2025-09-14T10:00:00.0000000Z"
   }
}

RavenDB will remove the @refresh metadata field at the specified time. That is all this does, nothing else. That looks like a pretty useless feature, I admit, but there is a point to it.

The act of removing the @refresh field from the document will also (obviously) update the document, which means that everything that reacts to a document update will also react to this.

I wrote about this in the past, but it turns out there are a lot of interesting things you can do with this. For example, consider the following index definition:

from RoomAvailabilitiesas r
where true and not exists(r."@metadata"."@refresh")
select new { 
  r.RoomId,
  r.Date,
  // etc...
}

What you see here is an index that lets me “hide” documents (that were reserved) until that reservation expires.

I can do quite a lot with this feature. For example, use this in RabbitMQ ETL to build automatic delayed sending of documents. Let’s implement a “dead-man switch”, a document will be automatically sent to a RabbitMQ channel if a server doesn’t contact us often enough:

if (this['@metadata']["@refresh"]) 
    return; // no need to send if refresh didn't expire


var alertData = {
    Id: id(this),
    ServerId: this.ServerId,
    LastUpdate: this.Timestamp,
    LastStatus: this.Status || 'ACTIVE'
};


loadToAlertExchange(alertData, 'alert.operations', {
    Id: id(this),
    Type: 'operations.alerts.missing_heartbeat',
    Source: '/operations/server-down/no-heartbeat'
});

The idea is that whenever a server contacts us, we’ll update the @refresh field to the maximum duration we are willing to miss updates from the server. If that time expires, RavenDB will remove the @refresh field, and the RabbitMQ ETL script will send an alert to the RabbitMQ exchange. You’ll note that this is actually reacting to inaction, which is a surprisingly hard thing to actually do, usually.

You’ll notice that, like many things in RavenDB, most features tend to be small and focused. The idea is that they compose well together and let you build the behavior you need with a very low complexity threshold.

The common use case for @refresh is when you use RavenDB Data Subscriptions to process documents. For example, you want to send an email in a week. This is done by writing an EmailToSend document with a @refresh of a week from now and defining a subscription with the following query:

from EmailToSend as e
where true and not exists(e.'@metadata'.'@refresh')

In other words, we simply filter out those that have a @refresh field, it’s that simple. Then, in your code, you can ignore the scheduling aspect entirely. Here is what this looks like:

var subscription = store.Subscriptions
    .GetSubscriptionWorker<EmailToSend>("EmailToSendSubscription");


await subscription.Run(async batch =>
{
    using var session = batch.OpenAsyncSession();
    foreach (var item in batch.Items)
    {
        var email = item.Result;
        await EmailProvider.SendEmailAsync(new EmailMessage
        {
            To = email.To,
            Subject = email.Subject,
            Body = email.Body,
            From = "no-reply@example.com"
        });


        email.Status = "Sent";
        email.SentAt = DateTime.UtcNow;
    }
    await session.SaveChangesAsync();
});

Note that nothing in this code handles scheduling. RavenDB is in charge of sending the documents to the subscription when the time expires.

Using @refresh + Subscriptions in this manner provides us with a number of interesting advantages:

Missed Triggers: Handles missed schedules seamlessly, resuming on the next subscription run.
Reliability: Automatically retries subscription processing on errors.
Rescheduling: When @refresh expires, your subscription worker will get the document and can decide to act or reschedule a check by updating the @refresh field again.
Robustness: You can rely on RavenDB to keep serving subscriptions even if nodes (both clients & servers) fail.
Scaleout: You can use concurrent subscriptions to have multiple workers read from the same subscription.

You can take this approach really far, in terms of load, throughput, and complexity. The nice thing about this setup is that you don’t need to glue together cron, a message queue, and worker management. You can let RavenDB handle it all for you.

Webinar: Building AI Agents in RavenDB

Tue, 16 Sep 2025 12:00:00 GMT

Tomorrow I’ll be giving a webinar on Building AI Agents in RavenDB. I’m going to show off some really cool ways to apply AI agents on your data, as well as our approach to AI and LLM in general.

I’m looking forward to seeing you there.

Caution: This is going to blow your mind.