Chapter 6. Advanced RavenDB Document Capabilities

Beyond storing a single document in RavenDB, there are many scenarios where you need to do more. The good thing is that RavenDB allows you to do more than just storing documents in its document store. In this chapter, you will learn different advanced techniques which you can apply to use RavenDB documents in an efficient way.

We will learn how to store and retrieve documents' attachment, how to handle documents' relationship, and how RavenDB can help you to do that in an easy way. Also you will learn how to patch, server side, a document or a set of documents using a simple syntax and discover how amazing ScriptedPatchRequest method is.

In this chapter we will cover:

• RavenDB attachments

• Handling documents relationships

• Patching documents

RavenDB attachments

Your application might require the storage of binary data in the database. For that you can choose to store this binary data in a field as part of a document in your database. In this case, the data will be stored and loaded with the document; this can work fine with a small binary data chunk. Large binary data is not recommended because it can increase the document size significantly. This is a result of increased I/O from disk and over the network.

The alternative is to use RavenDB attachments, which allows storage of large chunks of binary data such as video, audio, and images. Attachments are basically BLOBs (binary large object is a data type that can store binary data).

Note

If binary data is stored as part of a document, RavenDB will store this binary data base64-encoded in the document.

Storing attachments in RavenDB may not be the best choice for binary data. A better choice might be to store those data in a cloud environment or on dedicated servers.

Attachments...

Time for action – using attachments to store images

We want to add a flag image to a Country document and we want to store this image as an attachment. You will modify the Country class and add a new property to hold the FlagId value. Then you will add necessary code to store the attachment and modify a Country document to populate the FlagId property in order to refer the attachment. Once it is done, you will observe RavenDB logs to learn how RavenDB stores the attachment.

1. Start Visual Studio, create a new project and name it RavenDB_Ch06.

2. Add a new class, name it Country, and make it look like the following code snippet:

   

3. Add the following code to the Main() method:

   

4. Save all the files, build and run the solution.

5. In Windows Explorer, switch to the RavenDB prompt window and look at the RavenDB logs.

6. In Management Studio, use the Go To document "country/1098" to view this document with its new FlagId property.

What just happened?

We aim to attach a flag image file to a Country document from the...

Time for action – retrieving stored attachments

We want to retrieve the flag image we stored early as an attachment. You will add a code snippet to the Main() method to retrieve the attachment.

1. Start Visual Studio and open the RavenDB_Ch06 solution.

2. Add the following snippet of code to the Main() method:

   

3. Save all the files, build and run the solution.

4. In Windows Explorer, switch to the RavenDB prompt window and look at the RavenDB logs.

What just happened?

We aim to retrieve the flag image file stored earlier as an attachment.

Within the Main() method you called the GetAttachment() method on the DatabaseCommands object and specified the attachment ID to retrieve, which in this case is flag/1098.

This method returns an Attachment object that contains all data and metadata used to store the attachment.

To retrieve the attachment RavenDB performs a GET command on the static endpoint using the attachment ID:

Have a go hero – retrieving country flag image attachment

Write a new method to retrieve the...

Time for action – retrieving and updating anattachment's metadata

You will write two new methods to the Program class: the first method will retrieve the metadata information for a given attachment based on its key, the second method will update the metadata information for an attachment.

1. Start Visual Studio and open the RavenDB_Ch06 solution.

2. Add the following code to the Main() method:

   

3. Save all the files, build and run the solution.

What just happened?

We just retrieved the metadata information for the attachment with the ID as flag/1098 and updated them.

To retrieve the attachment metadata you call the HeadAttachment() method and specify the attachment key. This method returns the attachment header through which you can get its field values (line 65).

To update the metadata you called the UpdateAttachmentMetadata() method and provided the new metadata values (lines 73 to 79).

Have a go hero – updating and deleting attachments

Write two new methods to the Program class to update and delete an...

Handling documents relationships

Relational databases allow the user to create relationships between tables while in document databases the basic idea is that documents are independent.

Most of the advantages of document databases come from the document-oriented modeling. In a document-oriented model, data objects are stored as documents; each document stores your data and enables you to update the data or delete it. Analogous to the relational approach, complex parts (separate document(s)) can be implemented in a document, which will refer to these parts by a unique identifier.

However, in the document-model it is also possible to add a part as a property or collection inside the document representing the owner. In this case, if the owner is removed, the part will be removed with it automatically.

This approach is called data denormalization, where the owner document contains the actual value of the referenced entity in addition (or instead) to the foreign key. Therefore, this approach may...

Time for action – using Include to reduce query calls

Now let's take a look at how to handle document relationships while reducing query calls. You will make a call to the Load() method and the Include() method on the Session object to retrieve a City from the Cities collection and preload the Country referenced by the City.CountryId field. Then you will take a look at the RavenDB log and analyze its entries.

1. Open the RavenDB_Ch06 project in Visual Studio.

2. Copy the City class you created previously and make it a part of the RavenDB_Ch06 project.

3. Add the following code snippet to the Main() method:

   

   Tip

   You can specify more than one ID in the Load() method. In this case RavenDB will preload all related documents once and this will not require querying the server again.

4. Save all the files, build and run the solution.

5. In Windows Explorer, switch to the RavenDB prompt window and observe the RavenDB logs.

What just happened?

You just learned how to handle related documents in RavenDB. You called the...

Time for action – indexing related documents

You will create the Cities_RelatedCountry index which will implement the LoadDocuement() method. Then you will query this index while running the RavenDB_Ch06 project using the Management Studio.

1. Open the RavenDB_Ch06 project in Visual Studio.

2. Add a new class and name it Cities_RelatedCountry.

3. Complete the Cities_RelatedCountry class definition using the following code snippet:

   

4. Add the index's Map function within the class constructor using the following code snippet:

   

5. Add the following code snippet to the Main() method:

   

6. Save all the files, build and run the solution.

What just happened?

You just learned how to index related documents in RavenDB. In order to implement this feature, you called the LoadDocument() method within the Cities_RelatedCountry index's Map function.

The index's Map function defines three fields: Name, Population which will hold values from the City document, and CountryName which will hold information from the Country document....

Patching documents

Document patching is the way to modify a document on the server side without having to load it on the client side and saving it back. This is a great way to improve read and write performance. There are no documents sent to the client and no network bandwidth is used. Basically, a patch is a dedicated command that transforms server-side documents directly in the store.

RavenDB allows you to patch documents on the server side by sending either a JavaScript function to the server, or a command to the server with some instructions about how to modify a document (or a set of documents). This feature can be used to update a single document without the need to load the entire object or replacing its entire content.

You can apply patches on a document for creating, renaming, deleting a property, setting values, and so on.

There are many different types of patches supported by RavenDB. To apply a patch you need to call the Patch() method on the DatabaseCommands (on the Store object...

Time for action – applying a ScriptedPatchRequest

We will add the Language property to a Country document. This property will be set to EN (English) if the country's ContinentCode is NA and ES (Espagnol) if ContinentCode is SA. We want to apply this on all documents in the Countries collection.

1. Start Visual Studio and open the RavenDB_Ch06 project.

2. Add the following code snippet to the Main() method:

   

3. Save all the files, build and run the solution.

What just happened?

You just updated the Countries collection using a ScriptedPatchRequest written in JavaScript. During this update operation, you added a new property named language and populated it with values: EN or ES based on the country's ContinentCode.

To apply the update on Countries collection, you call the UpdateByIndex() method on the DatabaseCommands object (lines 129 to 142). This method performs a set-based update using the specified index and will not allow the update operation on a stale index.

This method requires the following three...

Time for action – using PatchRequest to add a new field to a document

We aim to add a new string field named FlagId to a document from the Countries collection. We arbitrarily choose the document with the ID as country/1005 (France) to apply the patch command. For that you will add the PatchingDocument() method to the Program class and then execute it.

1. Start Visual Studio and open the RavenDB_Ch06 project.

2. Add the following code to the Main() method:

   

3. Save all the files, build and run the solution.

4. In Windows Explorer, switch to RavenDB prompt window to look at its logs.

What just happened?

You just patched one item from the Countries collection by calling the Patch() method on the DatabaseCommands object. This patch operation aims to add the FlagId property to the Country field with the ID as country/1005.

In the previous code snippet (line 146) you call this method providing the document key (country/1005) to patch.

The Patch() method requests an array of PatchRequest object, you create a new...

Summary

In this chapter, we learned some advanced techniques which will help you use RavenDB documents in an efficient way. Specifically we covered RavenDB attachments and how to store them on the server and retrieve them back.

We also covered the Include feature and how to use it to preload related documents and optimize the read and write operations.

Finally, we covered RavenDB patching and how to update documents on the server side without the need to load them on the client side.

In the next chapter, we will talk about administrating RavenDB, its configuration options and some useful tasks such as customizing the RavenDB server using bundles and importing and exporting data. Keep reading!