Raven DB – Hello World

This will guide you throughout building your first Raven DB application.

• We start by heading to download page and getting the latest build.
• Unzip the downloaded file.
• Go to the /Server directory and double click on the Raven.Server.exe
  • This will start the RavenDB server listening on localhost:8080
  • If you already have an application listening on 8080, you can change the port RavenDB will listen to by editing the "Raven/Port" appSetting value in the Raven.Server.exe.config file.
  • RavenDB will automatically create a database in the /Data directory

• In Visual Studio, create a new console application project named: Raven.HelloWorld
• Add a reference to the Raven.Client.Lightweight.dll from the /Client directory
  • If you are using Visual Studio 2008, add a reference to Raven.Client-3.5.dll from /Client-3.5 directory

• Initialize the client:
  • DocumentStore should be created once per application and stored as a singleton.

  var store = new DocumentStore {Url = "http://localhost:8080"};
  store.Initialize();

• We define an entity model that we can work with:
  • Note that all the entities are POCO
  • The only requirement is that a root entity string Id property (configurable)

  public class Product
  {
      public string Id { get; set; }
      public string Name { get; set; }
      public decimal Cost { get; set; }
  }
  
  public class Order
  {
      public string Id { get; set; }
      public string Customer { get; set; }
      public IList<OrderLine> OrderLines { get; set; }
  
      public Order()
      {
          OrderLines = new List<OrderLine>();
      }
  }
  
  public class OrderLine
  {
      public string ProductId { get; set; }
      public int Quantity { get; set; }
  }

• Let us save some data:
  • The client API works using the session / data context model.
  • The client API implements the Unit of Work pattern.
  • Entity ids are only set when the SaveChanges method is called.

  using (var session = store.OpenSession())
  {
      var product = new Product
      {
          Cost = 3.99m,
          Name = "Milk",
      };
      session.Store(product);
      session.SaveChanges();
  
      session.Store(new Order
      {
          Customer = "customers/ayende",
          OrderLines =
                        {
                            new OrderLine
                            {
                                ProductId = product.Id,
                                Quantity = 3
                            },
                        }
      });
      session.SaveChanges();
  }

• Execute the code.
  • By default, RavenDB only allow authenticate users to modify documents and attachments.
  • The client API attempts to authenticate using the current user credentials.
  • You can set the credentials that the client API will use globally (set the DocumentStore.Credentials method) or per session (use the OpenSession(ICredentials) overload).
• Go to http://localhost:8080 in your browser.
• Click on the "documents" tab, it should look something like this:

The first two documents are the ones that we created, the third is part of the default documents that Ravens come with, including Raven's own documentation.

• Looking more closely at those documents, you can see that we have two documents:
  • Note that order lines are embedded inside the orders document. You can read more on this design decision.
  • Note the document keys: "products/1", "orders/1". Those are generated by Raven, the intend is to make them RESTful and human readable.

• And now let us get those documents back:
  

  using (var session = store.OpenSession())
  {
      var order = session.Load<Order>("orders/1");
      Console.WriteLine("Customer: {0}", order.Customer);
      foreach (var orderLine in order.OrderLines)
      {
          Console.WriteLine("Product: {0} x {1}", orderLine.ProductId, orderLine.Quantity);
      }
      session.SaveChanges();
  }

• Execute the code, which gives us:
  • If you'll look in Fiddler, you'll note that only one request was made, to get the entire object model.

• Now, for querying, we need to query all order that contains a particular product.
  • Raven requires you to define an index before you can query it.
  • Think about an index as a stored procedure.
  • You should only create an index once.

  store.DatabaseCommands.PutIndex("OrdersContainingProduct", new IndexDefinition<Order>
  {
      Map = orders => from order in orders
                      from line in order.OrderLines
                      select new { line.ProductId }
  });

• With the index in existence, we can now query it:
  • The query syntax in Raven is based on the Lucene syntax.
  • We call WaitForNonStaleResults because we just updated the database and Raven updates indexes on the background.
    • Normally you shouldn't call this method!

   using (var session = store.OpenSession())
   {
       var orders = session.LueneQuery<Order>("OrdersContainingProduct")
           .Where("ProductId:products/1")
           .WaitForNonStaleResults()
           .ToArray();
       foreach (var order in orders)
       {
           Console.WriteLine("Id: {0}", order.Id);
           Console.WriteLine("Customer: {0}", order.Customer);
           foreach (var orderLine in order.OrderLines)
           {
               Console.WriteLine("Product: {0} x {1}", orderLine.ProductId, orderLine.Quantity);
           }
       }
   }

• Which gives this output:
  

This is all, we have seen how we can read, write and query Raven. We worked with the client API and seen how we can persist .NET entities into Raven.