RavenDB version 2.5. Other versions:

RavenDB Collections

RavenDB's collections are similar to MongoDB's collections, they serve as a simple way to group related documents together. The expected usage pattern is that collections are used to group documents with similar structure, although that is not required. From the database standpoint, a collection is just a group of documents that share the same entity name.

Raven-Entity-Name

Collections are defined in the document metadata, more specifically, the collection a document belongs to is specified as the value of doc["@metadata"]["Raven-Entity-Name"]. Using the HTTP API, we can define the following document in the "Users" collection.

PUT http://localhost:8080/docs/users/ayende HTTP/1.1  
Raven-Entity-Name: Users  
Host: localhost:8080  
Content-Length: 23

{ "Name": "Ayende" }

As you can see, the HTTP header Raven-Entity-Name specifies that this document belongs to the Users collection.

Using collections in indexes

Probably the most important role for collections is their use in indexes. RavenDB allows the use of the collection name when filtering the target audience for documents. For example, this index definition:

    {
		'Map' : 'from post in docs.Posts select new { post.Title, post.PostedAt};'
	}

More formally, Raven filters the selected documents based on the name of the collection from the overall docs. The index definition above is equivalent to the following index definition:

    {
		'Map' : 'from doc in docs  
				where doc["@metadata"]["Raven-Entity-Name"] == "Posts"  
				let post = doc  
				select new { post.Title, post.PostedAt };'
	}

Using collections in this manner significantly simplifies the index definition and is strongly recommended.

Raven/DocumentsByEntityName

By default, RavenDB defines the index 'Raven/DocumentsByEntityName' as follows:

    {  
		'Map' : 'from doc in docs 
					let Tag = doc["@metadata"]["Raven-Entity-Name"]
					select new { Tag, LastModified = (DateTime)doc["@metadata"]["Last-Modified"] };'  
	}

This allows querying for documents based on their entity name using:

    http://localhost:8080/indexes/Raven/DocumentsByEntityName?query=Tag:Users

	{
		"Results":[ 
			{
				"Name":"Ayende",
				"@metadata":{
				"Raven-Entity-Name":"Users",
				"@id":"users/ayende",
				"@etag":"ecdb775b-4c96-11df-8ec2-001fd08ec235"
				}
			}
		],  
		"IsStale":false,  
		"TotalResults":1  
	}
Comments add new comment

The comments section is for user feedback or community content. If you seek assistance or have any questions, please post them at our support forums.

Eric Stanfield
REPLY Posted by Eric Stanfield on

Can a document belong to more than one different collection? If so, how?

Example Scenario: A piece of hardware produces log data continuously. These data are relevant for a specific period of time and at the end of that time it is downloaded from the hardware into a log file. That log file is stored in a document in RavenDB. The owner of the hardware can change from time to time and one owner can own several different pieces of hardware. I would like to store the specific hardware id as a raven-entity-name but also owner, with the objective being to be able to use both as collections.

Ayende Rahien
REPLY Posted by Ayende Rahien on

No, a document can below only to a single collection. What you are trying to do is NOT collections, however. Collections usually refer to the data type / shape / purpose.

You question, in RDBMS terms, is the same as "can a row be in more than one table?"

Matt Watson
REPLY Posted by Matt Watson on

Please add to this page an example using the .NET API for specifying the collection when creating new documents. This part is still very foggy. Seems like it is populating by the API doing a GetType() on the object passed in. But what about dynamic types?

Yong Liang
REPLY Posted by Yong Liang on

Hi, I noticed that you didn't mentioned how can we specify the collection name when adding new documents. Does the Raven support manually defining collection name by client user? as I know Mongo can do that. and there are scenarios that we want to create a collection which has hierarchical name like 'Orders.Drinks', this is like a namespace collection is useful to organize the documents in DB. Do the Raven DB support those and how can I do that? thanks!

SUBMIT COMMENT