RavenDB 2.x Beginner’s Guide

By Khaled Tannir

Written in a friendly, example-driven Beginner’s Guide format, there are plenty of step-by-step instructions and examples that are designed to help you get started with RavenDB. If you are a .NET developer, new to document-oriented databases, and you wish to learn how to build applications using NoSQL databases, then this book is for you. Experience with relational database systems will be helpful, but not necessary.

• Language: English
• Publisher: Packt Publishing
• Release date: Sep 4, 2013
• ISBN: 9781783283804

Book preview

Table of Contents

RavenDB 2.x Beginner's Guide

Credits

About the Author

Acknowledgments

About the Reviewers

www.PacktPub.com

Support files, eBooks, discount offers and more

Why Subscribe?

Free Access for Packt account holders

Preface

What this book covers

What you need for this book

Who this book is for

Conventions

Reader feedback

Customer support

Downloading the example code

Errata

Piracy

Questions

1. Getting Started with RavenDB

Understanding the basics of NoSQL Databases

Types of NoSQL Databases

What is RavenDB?

From relational databases to RavenDB

Why RavenDB?

How RavenDB works?

Anatomy of a Document

The JSON format

Downloading and installing RavenDB

What do you need to run RavenDB?

Time for action – downloading and installing RavenDB

What just happened?

Running RavenDB server in the Console mode

Exploring the Start.cmd file

Time for action – exploring the Start.cmd file

What just happened?

Configuring the RavenDB server

Launching the RavenDB server in the Console mode

Time for action – launching RavenDB in the Console mode

What just happened?

Creating your first RavenDB database

Time for action – creating a new database and adding sample data

What just happened?

Shutting down the RavenDB server in the Console mode

Time for action – shutting down RavenDB

What just happened?

Have a go hero – connecting to a RavenDB server on a networked computer

Summary

2. RavenDB Management Studio

Introducing the RavenDB Management Studio

Management Studio's multi-databases feature

Creating a new database

Time for action – creating a new database

What just happened?

Management Studio's Documents screen

Time for action – creating your first document

What just happened?

Time for action – loading a document

What just happened?

Time for action – searching for a document

What just happened?

Exporting a database to a CSV file

Time for action – exporting documents to a CSV file

What just happened?

RavenDB documents metadata

Time for action – adding a custom metadata key

What just happened

Management Studio's Collections screen

Time for action – modifying a document

What just happened?

Management Studio's Indexes screen

Creating your first Index

Time for action – creating an Index

What just happened?

Executing a query against an Index

Time for action – querying an Index

What just happened?

Editing an Index

Time for action – editing an Index

What just happened?

The Query Index screen

Time for action – querying an Index

What just happened?

Creating a Dynamic Query

Time for action – creating a Dynamic Query

What just happened?

Management Studio's Patch screen

Time for action – patching a document

What just happened?

Have a go hero – patching the Orders collection

Management Studio's Tasks screen

Time for action – importing external data using a CSV file

What just happened?

Have a go hero – exporting documents from different views

Management Studio's Alerts screen

Management Studio's Logs screen

Time for action – exploring the Logs screen

What just happened?

Viewing the database settings

Time for action – viewing the database's active bundles

What just happened?

The System database settings

Time for action – opening the System database's Settings page

What just happened?

Bundles

Time for action – enabling the Periodic Backup feature

What just happened?

Doing more with the Management Studio

Choosing the columns

Time for action – customizing the columns

What just happened?

Copying the document to clipboard

Time for action – copying the data document to the clipboard

What just happened?

Deleting the Documents, Collections, Indexes, or Databases

Time for action – deleting a database using the Management Studio

What just happened?

Summary

3. RavenDB.NET Client API

The RavenDB .NET Client API

Setting up your development environment

Time for action – installing NuGet Package Manager

What just happened?

Creating a simple application

Time for action – adding RavenDB Client to a Visual Studio project

What just happened?

Connecting to RavenDB

Time for action – connecting to RavenDB

What just happened?

Interacting with RavenDB using the .NET Client API

Loading a document

Time for action – loading a document

What just happened?

Have a go hero – loading multiple documents

Inserting a new Document

Time for action – inserting a new document

What just happened?

Updating a document

Time for action – updating a document

What just happened?

Deleting a document

Time for action – deleting a document

What just happened?

Querying a documents collection

Time for action – querying a documents collection

What just happened?

Have a go hero – querying a collection using lambda expression

Pop quiz – RavenDB .NET Client API

Summary

4. RavenDB Indexes and Queries

The RavenDB indexes

RavenDB Map/Reduce implementation

The types of RavenDB indexes

RavenDB dynamic indexes

Querying dynamic indexes

Time for action – querying a dynamic index

What just happened?

Querying temporary indexes

Time for action – querying a temporary index

What just happened?

Managing temporary indexes

Time for action – managing temporary indexes

Have a go hero – creating projections using Linq queries

RavenDB static indexes

Creating your first Map function

Time for action – defining a Map function for an index

What just happened?

Creating your first Reduce function

Time for action – adding a Reduce function to an index

What just happened?

Using TransformResults in an index

Time for action – adding a TransformResults to the index

What just happened?

Have a go hero – creating Map/Reduce/Transform index

RavenDB stale indexes

Checking for stale index results

Time for action – checking for stale index results

What just happened?

Waiting for non-stale index results

Time for action – explicitly waiting for a non-stale index result

What just happened?

Have a go hero – display all index names

Pop quiz – RavenDB and Map/Reduce

Summary

5. Advanced RavenDB Indexes and Queries

The RavenDB AbstractIndexCreationTask class

Creating indexes using the AbstractIndexCreationTask class

Time for action – creating indexes using AbstractIndexCreationTask class

What just happened?

Using AbstractIndexCreationTask and ReduceResult

Time for action – creating indexes using the ResultReduce class

What just happened?

Have a go hero – query the Cities_SameName index

Using the TransformResults function

Time for action – using the TransformResults function

What just happened?

Creating multimap indexes

Time for action – creating multimap indexes

What just happened?

Using indexes to search over documents

Full-text and exact matching search

Time for action – creating a full-text searching index

What just happened?

Have a go hero – adding exact matching searching index class

Multiple field searching and search options

Time for action – creating multifields searching index

What just happened?

Using a custom analyzer for searching

Time for action – using a custom analyzer

What just happened?

Paging a query's results

Time for action – paging a query's results

What just happened?

Pop quiz – searching the right way

Summary

6. Advanced RavenDB Document Capabilities

RavenDB attachments

Storing attachments

Time for action – using attachments to store images

What just happened?

Retrieving attachments

Time for action – retrieving stored attachments

What just happened?

Have a go hero – retrieving country flag image attachment

Update and delete attachments

Time for action – retrieving and updating anattachment's metadata

What just happened?

Have a go hero – updating and deleting attachments

Handling documents relationships

Using Include to preload documents

Time for action – using Include to reduce query calls

What just happened?

Have a go hero – using Include with a query

Indexing related documents

Time for action – indexing related documents

What just happened?

Patching documents

Patching documents using ScriptedPatchRequest

Time for action – applying a ScriptedPatchRequest

What just happened?

Patching documents using PatchRequest

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

What just happened?

Have a go hero – adding a FlagId field to the Countries collection

Summary

7. RavenDB Administration

RavenDB configuration options

RavenDB optimizing key concepts

Time for action – optimizing RavenDB performances

What just happened?

Backing up RavenDB databases

Backing up databases using the RavenDB backup tool

Time for action – backing up the World database

What just happened?

Have a go hero – creating an incremental backup

Backing up a database using VSS

Backing up a database using Management Studio

Time for action – backing up the World database using Management Studio

What just happened?

Restoring RavenDB databases

Restoring databases using the command line

Time for action – restoring the World database using the command line

What just happened?

Restoring databases using Management Studio

Time for action – restoring the World database using Management Studio

What just happened?

Exporting and importing RavenDB databases

Exporting RavenDB databases

Time for action – exporting the World database using Smuggler

What just happened?

Importing RavenDB databases

Time for action – importing the World database using Smuggler

What just happened?

Have a go hero – importing/exporting using the Client .NET API

Deleting RavenDB databases

RavenDB server bundles

Replication bundles

RavenDB replication bundle

Time for action – creating a master to slave database replication

What just happened?

Have a go hero – creating World database replication

SQL replication bundle

Time for action – replicating to Microsoft SQL Express

What just happened?

Have a go hero – activating and using the IndexReplication bundle

RavenDB authorization bundle

Time for action – authenticating and authorizing

What just happened?

Have a go hero – activating the authorization bundle

Enabling RavenDB logging

Time for action – enabling RavenDB logging

What just happened?

Upgrading the RavenDB server

Time for action – upgrading the RavenDB server

Pop quiz – RavenDB administration

Summary

8. Deploying RavenDB

RavenDB deployment strategies

Running RavenDB as a Windows Service

Installing the RavenDB service

Time for action – running RavenDB as a Windows Service

What just happened?

Have a go hero – setting a particular host name to RavenDB

Uninstalling the RavenDB service

Time for action – uninstalling the RavenDB service

What just happened?

RavenDB and IIS

Running RavenDB from an IIS virtual directory

Time for action – running RavenDB from an IIS virtual directory

What just happened?

Running RavenDB as an IIS application

Time for action – running RavenDB as an IIS application

What just happened?

RavenDB Embedded mode

Embedding RavenDB

Time for action – running RavenDB in Embedded mode

What just happened?

Memory embedded RavenDB

Time for action – running RavenDB inmemory

What just happened?

Pop quiz – searching the right way

Summary

9. Scaling-out RavenDB

What is scaling-out?

RavenDB sharding

Time for action – preparing RavenDB for sharding

What just happened?

RavenDB sharding – the blind mode

Time for action – implementing RavenDB sharding (the blind mode)

What just happened?

RavenDB sharding – the smart mode

Time for action – implementing RavenDB sharding (the smart mode)

What just happened?

Have a go hero – implementing the Shard ID translator function

Mixing sharding and replication

Have a go hero – mixing sharding and replication

Pop Quiz – scaling-out RavenDB

Summary

10. RavenDB Profiling

What is profiling?

RavenDB profiler

Time for action – enabling the RavenDB profiler

What just happened?

Using the profiler information

Have a go hero – profiling the RavenDB shards

RavenDB visual host

Time for action – running the RavenDB visual host

What just happened?

RavenDB workload simulator/stress tests

Summary

11. RavenDB HTTP API

The RavenDB HTTP API

Understanding REST

Anatomy of the RavenDB REST request URL

The RESTClient tool

Time for action – downloading and launching the RESTClient tool

What just happened?

The GET request

Time for action – performing a GET request

What just happened?

Have a go hero – retrieving the databases list

The PUT request

Time for action – granting access to perform a PUT request

What just happened?

Time for action – performing a PUT request

What just happened?

The POST request

Time for action – performing a POST request

What just happened?

Have a go hero – retrieving the inserted document

The PATCH request

Time for action – performing a Patch request

What just happened?

Have a go hero – removing the document properties with a PATCH request

The DELETE request

Time for action – performing a Delete request

What just happened?

Getting multiple documents with a single request

Time for action – getting multiple documents within a single request

What just happened?

Querying an Index

Time for action – querying an Index

What just happened?

Pop Quiz – deep into RavenDB

Summary

12. Putting It All Together

A word about ASP.NET MVC

Application architecture key concepts

Creating an ASP.NET MVC 4 project with RavenDB

Getting connected to RavenDB

Time for action – creating the World ASP.NET MVC application

What just happened?

Adding Models

Time for action – adding the World application's Models

What just happened?

Adding Controllers

Time for action – adding the Controllers

What just happened?

Have a go hero – adding the CityController class

Adding Views

Time for action – adding the Views

What just happened?

Have a go hero – adding the CityController Views

Launching the World application

Time for action – launching the World application

What just happened?

Doing more with the World application

Creating the RavenDB Indexes automatically

Time for action – creating indexes automatically

What just happened?

Adding a page navigation bar

Time for action – the paging query () result

What just happened?

Adding the Country master/details View

Time for action – creating the Country master/details View

What just happened?

Adding the search Cities view

Time for action – implementing the Search view

What just happened?

Have a go hero – creating the Search view with paginated result

Summary

13. Pop Quiz Answers

Chapter 3, RavenDB.NET Client API

Pop quiz – RavenDB .NET Client API

Chapter 4, RavenDB Indexes and Queries

Pop quiz – RavenDB and Map/Reduce

Chapter 5, Advanced RavenDB Indexes and Queries

Pop quiz – searching the right way

Chapter 7, RavenDB Administration

Pop quiz – RavenDB administration

Chapter 9, Scaling-out RavenDB

Pop quiz – scaling-out RavenDB

Chapter 11, RavenDB HTTP API

Pop quiz – deep into RavenDB

Index

RavenDB 2.x Beginner's Guide

---

RavenDB 2.x Beginner's Guide

Copyright © 2013 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

First published: September 2013

Production Reference: 1280813

Published by Packt Publishing Ltd.

Livery Place

35 Livery Street

Birmingham B3 2PB, UK.

ISBN 978-1-78328-379-8

www.packtpub.com

Cover Image by Khaled Tannir (<[e-mail]>)

Credits

Author

Khaled Tannir

Reviewer

Alonso Robles

Oren Eini

Acquisition Editor

Anthony Albuquerque

Lead Technical Editor

Sweny Sukumaran

Technical Editors

Sampreshita Maheshwari

Chandni Maishery

Project Coordinator

Shiksha Chaturvedi

Proofreader

Mario Cecere

Paul Hindle

Indexer

Tejal Soni

Graphics

Ronak Dhruv

Abhinash Sahu

Production Coordinator

Pooja Chiplunkar

Cover Work

Pooja Chiplunkar

About the Author

Khaled Tannir has been working with computers since 1980. He began programming with the legendary Sinclair Zx81 and with Commodore home computer products (Vic 20, Commodore 64, Commodore 128D, and Amiga 500).

He has a Bachelor's degree in Electronics, a Master's degree in System Information Architectures, in which he graduated with a professional thesis, and completed his education with a Research Master's degree.

He is a Microsoft Certified Application Developer (MCAD) and has more than twenty years of technical experience leading the development and implementation of software solutions and giving technical presentations. He now works as an independent IT consultant and has worked as an infrastructure engineer, senior developer, and enterprise/solution architect for many companies in France and Canada. With very significant experience in Microsoft .NET and Microsoft Servers Systems, he has extensive skills in online/offline applications design, system conversions, and multilanguage applications.

He is always researching new technologies, learning about them, and looking for new adventures between France, Canada, and the Middle-east. He owns an IT and electronics laboratory with many servers, monitors, open electronics boards such as Arduino, Netduino, RaspBerry, and .NET Gadgeteer, and some smartphone devices based on Windows Phone, Android, and iOS operating systems.

In 2012, he contributed to the EGC 2012 (International Complex Data Mining forum at Bordeaux University, France) and presented, in a workshop session, his work about how to optimize data distribution in a cloud computing environment. This work aims to define an approach to optimize the of Data Mining algorithms such as k-means and Apriori in a cloud computing environment.

He aims to get a PhD in Cloud Computing and Big Data and wants to learn more and more about these technologies.

He enjoys taking landscape and night photos, traveling, playing video games, creating funny electronic gadgets with Arduino/.NET Gadgeteer, and, of course, spending time with his wife and family.

You can reach him at <[e-mail]>

Acknowledgments

All praise is due to Allah, the Lord of the Worlds. First, I must thank Allah for giving me the ability to think and write.

Next, I would like to thank my wife, Laila, for her big support and patience throughout this project. Also, I would like to thank my brother Khalil for his support during this project.

I would like to thank everyone at Packt Publishing for their help and guidance, and for giving me the opportunity to share my experience and my knowledge in technology with others in the .NET NoSQL community.

Thank you as well to the technical reviewers, who provided great feedback to ensure that every tiny technical detail was accurate and rich in content.

About the Reviewers

Alonso Robles is a husband, a father, and is currently a Principal Consultant at Headspring, a leading software development company. He has developed numerous software solutions over the last decade, solving real business problems for companies in many industries including, but not limited to, finance, insurance, biotech, entertainment, manufacturing, education, technology, and even local government. He is a passionate advocate for emerging technologies who believes in using the right tool for the right job. Most recently, his time has been focused on software projects that leverage various NoSQL technologies. Alonso can usually be found delivering technical presentations at various community events, leading multiday training curriculums, and even authoring blog posts and white papers.

Oren Eini has over 15 years of experience in the development world with a strong focus on the Microsoft and .NET ecosystem, and has been awarded Microsoft's Most Valuable Professional since 2007.

An internationally known presenter, Oren has spoken at conferences such as DevTeach, JAOO, QCon, Oredev, NDC, Yow! and Progressive.NET.

Oren is the author of the book DSLs in Boo: Domain Specific Languages in .NET, published by Manning (http://manning.com/rahien/).

Oren's main focus is on architecture and best practices that promote quality software and zero-friction development.

Oren, using his pseudonym as Ayende Rahien, is a frequent blogger at http://www.ayende.com/Blog/.

Oren Eini is the founder of Hibernating Rhinos LTD, an Israel-based company, offering:

Consulting and mentoring services

Code reviews

Architectural reviews and system design

Developer productivity tools for OLTP applications such as:

NHibernate Profiler (nhprof.com)

Linq to SQL Profiler (l2sprof.com)

Entity Framework Profiler (efprof.com)

LLBLGen Profiler (llblgenprof.com)

No SQL solutions

RavenDB - a native .NET second generation document database (ravendb.net)

RavenMD - a native .NET distributed queuing and messaging system (soon to be released)

Oren is the author of Rhino Mocks, one of the most popular mocking frameworks on the .NET platform, and is also a leading figure in other well known open source projects including:

NHibernate

RavenDB

Rhino Tools Suite

Rhino Mocks - mocking framework

Rhino Commons - infrastructure framework

Rhino Igloo - MVC framework for WebForms

Rhino Security - security infrastructure for NHibernate

Rhino DSL - Domain Specific Language building toolkit

Rhino ESB - Distributed Service Bus framework

Rhino Licensing - licensing infrastructure

Rhino ETL - Extract/Transform/Load framework

Rhino PHT - Persistent Hash Table for .NET

Rhino DHT - Distributed Hash Table for .NET

Rhino Queues - Distributed queuing infrastructure

Castle project

His hobbies include reading fantasy novels, reviewing code, and writing about himself in the third person.

www.PacktPub.com

Support files, eBooks, discount offers and more

You might want to visit www.PacktPub.com for support files and downloads related to your book.

Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at www.PacktPub.com and as a print book customer, you are entitled to a discount on the eBook copy. Get in touch with us at for more details.

At www.PacktPub.com, you can also read a collection of free technical articles, sign up for a range of free newsletters and receive exclusive discounts and offers on Packt books and eBooks.

http://PacktLib.PacktPub.com

Do you need instant solutions to your IT questions? PacktLib is Packt's online digital book library. Here, you can access, read and search across Packt's entire library of books. 

Why Subscribe?

Fully searchable across every book published by Packt

Copy and paste, print and bookmark content

On demand and accessible via web browser

Free Access for Packt account holders

If you have an account with Packt at www.PacktPub.com, you can use this to access PacktLib today and view nine entirely free books. Simply use your login credentials for immediate access.

Preface

RavenDB is an open source second generation NoSQL document database written in .NET. With its schema-less and flexible data model, it is designed to meet the real-world applications and allow you to build high-performance applications quickly and efficiently.

RavenDB 2.x Beginner's Guide introduces RavenDB concepts to the .NET developer who has some background in building desktop and web applications.

This book teaches you everything, right from installing RavenDB to creating documents and querying indexes using the .NET Client API through a series of clear and practical exercises. It starts off with an introduction to RavenDB and its Management Studio before moving on to cover dynamic and static indexes that use Map/Reduce to process datasets. With the help of detailed examples, you will learn how to create, manage, and query these indexes. Also, you will learn how to manage document attachments and patching documents using JavaScript.

With this book, you will learn how to deploy RavenDB in a production environment and how to profile and optimize it to boost performance. You will also learn how to create shards and implement replication to improve data availability and how to interact with RavenDB using the HTTP API.

Finally, you will learn to create an ASP.NET MVC application that uses RavenDB as a baking store to put all learned concepts together.

What this book covers

Chapter 1, Getting Started with RavenDB, introduces the underlying concepts of RavenDB and provides a step-by-step guide on how to install and run a RavenDB server on a computer to create your first RavenDB database.

Chapter 2, RavenDB Management Studio, introduces the RavenDB Silverlight client to let you easily manage documents in RavenDB. You will learn to view, create, edit, or delete documents, as well as how to manage indexes, issue queries, view the errors log, import/export, and so on.

Chapter 3, RavenDB .NET Client API, covers all aspects to interact with RavenDB using the Microsoft .NET framework. You will learn to connect to RavenDB, create, update, and delete documents, and how to query a document collection.

Chapter 4, RavenDB Indexes and Queries, covers RavenDB dynamic, static, and stales indexes. You will learn to create and query RavenDB Map/Reduce indexes and learn to manage temporary indexes.

Chapter 5, Advanced RavenDB Indexes and Queries, introduces the AbstractIndexCreationTask class and shows you how to use it to create the Map/Reduce indexes. Also, you will learn how to create multi-map indexes, use the TransformResults function, search over documents, and page query results.

Chapter 6, Advanced RavenDB Document Capabilities, explores the RavenDB document attachments and shows you how to handle document relationships using the Include statement and how to patch a document or a document collection using JavaScript.

Chapter 7, RavenDB Administration, shows you how to configure, backup, restore, import, and export RavenDB databases. Also, this chapter explores RavenDB bundles and you will learn to implement the SQL replication bundle to replicate data to Microsoft SQL Server.

Chapter 8, Deploying