In an effort to consolidate all Azure information in one place we have moved to https://azure.microsoft.com/blog/.
Don't worry, if you're looking for just DocumentDB posts then you can filter for just DocumentDB posts by using tags - https://azure.microsoft.com/blog/tag/documentdb/.

However, I encourage you to at least scan all the other posts as we are adding a ton of cool new features to Azure all the time.

You can still follow us on Twitter at @DocumentDB.

1. Tokenizing words

The first method is easy to implement and works well when your requirements are relatively simple word matching. Consider a document that looks like the JSON below:

{
    "id": "CDC101",
    "title": "Fundamentals of database design",     "credits":  10
}

How would I search for all documents that had the word ‘database’ in the title field? A simple way to do this would be to tokenize the title field and create JSON as below:

{
    "id": "CDC101",
    "title": "Fundamentals of database design",
    "titleWords": [ "fundamentals", "database", "design" ],
    "credits":  10
}

Note:  consider using a RegEx to transform words to lowercase and remove any punctuation. Also, strip out stop words like “to”, “the”, “of”  etc. (https://en.wikipedia.org/wiki/Stop_words)

Now searching for words in the title becomes easy with the following query:

SELECT r FROM root r JOIN word IN r.titleWords WHERE word = "database" 

2. Using Azure Search

If you have several words to tokenize, you accommodate the extra storage required to store the additional array of words, or you need more complex multi-faceted full-text searching capabilities across multiple fields etc. then the above approach will not work for you and you need the assistance of a more powerful full-text capable search engine. Luckily Azure has one of these that is super easy to setup and use, it is called Azure Search.

You can setup a data source pointing to your DocumentDB database and have a Search indexer crawl through your data on a predefined schedule.

For detailed steps on setting this up, check out Connecting DocumentDB with Azure Search using indexers. You can also download a sample ASP.NET MVC web application using DocumentDB and Search together.

In order to run this sample, simply create a Search account and a DocumentDB account. Once you have these, update the web.config with your endpoints and keys (obtainable from the Azure Management Portal).

The download includes sample todo items which you can import in to DocumentDB if you want to start with some canned data, or you can just crack open the solution in Visual Studio and run the project to start with a clean slate.

Add some todo items, hit the index button to force a manual re-index and then go do some searching.

So, there you have it – > Searching for text within DocumentDB is easy!

To learn more about DocumentDB, visit our service page and to learn more about DocumentDB query syntax, please visit our Query Playground page.

Azure DocumentDB allows you to tune the performance of your database to best meet the needs of your application.  In part 1 of this series, we looked at networking and SDK configuration options available in DocumentDB and their impact on performance. This post will continue the discussion and cover the performance impact of indexing policies, throughput optimization and consistency levels.  Like any performance tuning recommendation, not every one of these tips may be applicable for your use case, but you can use this information as a guide in order to assist you in making the right design choices for your applications.

INDEXING POLICY

Indexing Policy Tip #1: Use lazy indexing for faster peak time ingestion rates

DocumentDB allows you to specify – at the collection level – an indexing policy, which enables you to choose if you want the documents in a collection to be automatically indexed or not.  In addition, you may also choose between synchronous (Consistent) and asynchronous (Lazy) index updates. By default, the index is updated synchronously on each insert, replace or delete of a document to the collection. This enables the queries to honor the same consistency level as that of the document reads without any delay for the index to “catch up".

Lazy indexing may be considered for scenarios in which data is written in bursts, and you want to amortize the work required to index content over a longer period of time. This allows you to use your provisioned throughput effectively and serve write requests at peak times with minimal latency. It is important to note, however, that when lazy indexing is enabled, query results will be eventually consistent regardless of the consistency level configured for the DocumentDB account.

Hence, Consistent indexing mode (IndexingPolicy.IndexingMode is set to Consistent) incurs the highest request unit charge per write, while Lazy indexing mode (IndexingPolicy.IndexingMode is set to Lazy) and no indexing (IndexingPolicy.Automatic is set to False) have zero indexing cost at the time of write.

Indexing Policy Tip #2: Exclude unused paths from indexing for faster writes

DocumentDB’s indexing policy also allows you to specify which document paths to include or exclude from indexing by leveraging Indexing Paths (IndexingPolicy.IncludedPaths and IndexingPolicy.ExcludedPaths). The use of indexing paths can offer improved write performance and lower index storage for scenarios in which the query patterns are known beforehand, as indexing costs are directly correlated to the number of unique paths indexed.  For example:

//exclude index paths

collection.IndexingPolicy.ExcludedPaths.Add("/\"metaData\"/*"); collection.IndexingPolicy.ExcludedPaths.Add("/\"subDoc\"/\"subSubDoc\"/\"someProperty\"/*");
collection = await client.CreateDocumentCollectionAsync(databaseLink, collection);

Indexing Policy Tip #3: Specify range index path type for all paths used in range queries

DocumentDB currently supports two index path types: Hash and Range. Choosing an index path type of Hash enables efficient equality queries. Choosing an index type of Range enables range queries (using >, <, >=, <=).   For example:

var collection = new DocumentCollection
{
    Id = ConfigurationManager.AppSettings["CollectionId"]
};

collection.IndexingPolicy.IncludedPaths.Add(new IndexingPath
{
    IndexType = IndexType.Hash,
    Path = "/",
});

collection.IndexingPolicy.IncludedPaths.Add(new IndexingPath
{
    IndexType = IndexType.Range,
    Path = @"/""shippedTimestamp""/?",
    NumericPrecision = 7
});

collection = await client.CreateDocumentCollectionAsync(databaseLink, collection);

Indexing Policy Tip #4: Vary index precision for write vs query performance vs storage tradeoffs

Finally, indexing policies allow you to change the index path precision in bytes to improve query performance. Queries against a path indexed with a higher precision are typically faster, but incur a correspondingly higher storage overhead for the index. Conversely, choosing a lower precision means that more documents might have to be processed during query execution, but the storage overhead will be lower.

For more details on indexing policies, refer to this documentation.

Note: Currently in the Preview release the index policy for a collection can only be specified when a collection is created.

Throughput

Throughput Tip #1: Measure and Tune for lower request units/second usage

DocumentDB offers a rich set of database operations including relational and hierarchical queries with UDFs, stored procedures and triggers – all operating on the documents within a database collection. The cost associated with each of these operations will vary based on the CPU, IO and memory required to complete the operation. Instead of thinking about and managing hardware resources, you can think of a request unit (RU) as a single measure for the resources required to perform various database operations and service an application request.

Request units are provisioned for each Database Account based on the number of capacity units that you purchase. Request unit consumption is evaluated as a rate per second. Applications that exceed the provisioned request unit rate for their account will be throttled until the rate drops below the reserved level for the Account. If your application requires a higher level of throughput, you can purchase additional capacity units.

The complexity of a query impacts how many Request Units are consumed for an operation. The number of predicates, nature of the predicates, number of UDFs, and the size of the source data set all influence the cost of query operations.

To measure the overhead of any operation (create, update or delete), inspect the x-ms-request-charge header (or the equivalent RequestCharge property in ResourceResponse<T> or FeedResponse<T> in the .NET SDK) to measure the number of request units consumed by these operations.

// Measure the performance (request units) of writes

ResourceResponse<Document> response = await client.CreateDocumentAsync(collectionSelfLink, myDocument);

Console.WriteLine("Insert of document consumed {0} request units", response.RequestCharge);

// Measure the performance (request units) of queries

IDocumentQuery<dynamic> queryable = client.CreateDocumentQuery(collectionSelfLink, queryString).AsDocumentQuery();

while (queryable.HasMoreResults)
{

    FeedResponse<dynamic> queryResponse = await queryable.ExecuteNextAsync<dynamic>();

    Console.WriteLine("Query batch consumed {0} request units", queryResponse.RequestCharge);
}

The request charge returned in this header is a fraction of your provisioned throughput (i.e. 2000 RUs / second).   For example, if the query above returns 1000 1KB documents, the cost of the operation will be 1000. As such, within one second, the server will honor only two such requests before throttling subsequent requests.

Throughput Tip #2: Handle Server throttles/request rate too large 

When a client attempts to exceed the reserved throughput for an account, there will be no performance degradation at the server and no use of throughput capacity beyond the reserved level. The server will preemptively end the request with RequestRateTooLarge (HTTP status code 429) and return the x-ms-retry-after-ms header indicating the amount of time, in milliseconds, that the user must wait before reattempting the request.

HTTP Status 429,
Status Line: RequestRateTooLarge
x-ms-retry-after-ms :100

If you are using the .NET Client SDK and LINQ queries, then most of the time you never have to deal with this exception, as the current version of the .NET Client SDK implicitly catches this response, respects the server-specified retry-after header, and retries the request. Unless your account is being accessed concurrently by multiple clients, the next retry will succeed.

If you have more than one client cumulatively operating consistently above the request rate, the default retry currently set to 3 by the .NET client may not suffice; in this case, the client will throw a DocumentClientException with status code 429 to the application. Note that with the current release of the .NET SDK, there is no way to turn off the default retry count.

While the automated retry behavior helps to improve resiliency and usability for the most applications, it might come at odds when doing performance benchmarks, especially when measuring latency.  The client-observed latency will spike if the experiment hits the server throttle and causes the client SDK to silently retry. To avoid latency spikes during performance experiments, measure the charge returned by each operation and ensure that requests are operating below the reserved request rate.

Throughput Tip #3: Delete empty collections to utilize all provisioned throughput

Every document collection created in a DocumentDB account is allocated reserved throughput capacity based on the number of Capacity Units (CUs) provisioned, and the number of collections created.   A single CU makes available 2,000 request units (RUs) and supports up to 3 collections. If only one collection is created for the CU, the entire CU throughput will be available for the collection. Once a second collection is created, the throughput of the first collection will be halved and given to the second collection, and so on. By provisioning additional CUs, the throughput for an existing collection can be increased. During DocumentDB Preview, a single collection can scale up to 10 GB and can be allocated up to the maximum throughput of a single CU, which is 2000 request units/second. To maximize the throughput available per collections, ensure that the number of capacity units to collections is 1:1.

Throughput Tip #4: Design for smaller documents for higher throughput

The Request Charge (i.e. request processing cost) of a given operation is directly correlated to the size of the document. Operations on large documents cost more than operations for small documents.

CONSISTENCY LEVELS

Consistency Levels Tip #1: Use Weaker Consistency Levels for better Read latencies

Another important factor to take into account while tuning the performance of a DocumentDB applications is Consistency Level. The choice of consistency Level has performance implications for both reads and writes. You can configure the Default Consistency Level on the database account and the chosen Consistency Level then applies to all the collections (across all of the databases) within the DocumentDB account. In terms of write operations, the impact of changing consistency level is observed as request latency. As stronger consistency levels are used, write latencies will increase. On the other hand, the impact of consistency level on read operations is observed in terms of throughput. Weaker consistency levels allow higher read throughput to be realized by the client.

By default all reads and queries issued against the user defined resources will use the default consistency level specified on the database account. You can, however, lower the consistency level of a specific read/query request by specifying the x-ms-consistency-level request header.

WRAPPING UP

We hope that between this post and part 1 you’ve found performance tips which are both useful and applicable to your usage of DocumentDB. 

As always, we’d love to hear from you about the DocumentDB features and experiences you would find most valuable. 

Please submit your suggestions on the Microsoft Azure DocumentDB feedback forum. 

If you haven’t tried DocumentDB yet, then get started here.

Let's take a look at a sample using the .NET SDK; In addition to plain SQL strings and LINQ expressions, we've added a new SqlQuerySpec class that can be used to build parameterized queries.
Here's a sample that queries a "Books" collection with a single user supplied parameter for author name:

IQueryable<Book> queryable = client.CreateDocumentQuery<Book>(collectionSelfLink, new SqlQuerySpec {
                    QueryText = "SELECT * FROM books b WHERE (b.Author.Name = @name)",
                    Parameters = new SqlParameterCollection()  {
                          new SqlParameter("@name", "Herman Melville")
                     }
});

A few interesting things to note here:

• SQL parameters in DocumentDB use the familiar @ notation borrowed from T-SQL
• Parameter values can be any valid JSON (strings, numbers, Booleans, null, even arrays or nested JSON)
• Since DocumentDB is schema-less, parameters are not validated against any type
• We could just as easily supply additional parameters by adding additional SqlParameters to the SqlParameterCollection

The DocumentDB REST API also natively supports parameterization. The .NET sample shown above translates to the following REST API call. To use parameterized queries, you need to specify the Content-Type Header as application/query+json and the query as JSON in the body, as shown below.

POST https://contosomarketing.documents.azure.com/dbs/XP0mAA==/colls/XP0mAJ3H-AA=/docs
HTTP/1.1 x-ms-documentdb-isquery: True 
x-ms-date: Mon, 18 Aug 2014 13:05:49 GMT 
authorization: type%3dmaster%26ver%3d1.0%26sig%3dkOU%2bBn2vkvIlHypfE8AA5fulpn8zKjLwdrxBqyg0YGQ%3d 
x-ms-version: 2014-08-21 
Accept: application/json 
Content-Type: application/query+json 
Host: contosomarketing.documents.azure.com 
Content-Length: 50 
{      
    "query": "SELECT * FROM books b WHERE (b.Author.Name = @name)",     
    "parameters": [          
        {"name": "@name", "value": "Herman Melville"}         
    ] 
}

Queries can be issued against document collections, as well as system metadata collections like Databases, DocumentCollections, and Attachments using the approach shown above. To try this out, download the latest build of the DocumentDB SDK on any of the supported platforms (.NET, Java, Node.js, JavaScript, or Python).

*DocumentDB is not susceptible to the most common kinds of injection attacks that lead to “elevation of privileges” because queries are strictly read-only operations. However, it might be possible for a user to gain access to data they shouldn’t be accessing within the same collection by crafting malicious SQL queries. SQL parameterization support helps prevent these sort of attacks.

Azure DocumentDB allows you to optimize the performance of your database to best meet the needs of your application.  We’ve prepared a two part blog post series which will cover a number of areas that influence the performance of Azure DocumentDB.

In part 1, we look at the networking and SDK configuration options available in DocumentDB and their impact on performance. In part 2 we will cover indexing policy, throughput optimization and consistency levels.  Like any performance tuning recommendation, not every one of these tips may be applicable for your use case, but you can use this information as a guide in order to assist you in making the right design choices for your applications.

NETWORKING

Networking Tip #1 Connection Policy - Use direct connection mode for better performance

First, let’s take a look at Connection Policy. How a client connects to Azure DocumentDB has important implications on performance, especially in terms of observed client-side latency. There are two key configuration settings available for configuring client Connection Policy – the connection mode and the connection protocol.  The two available modes are:

1. Gateway Mode (default)
2. Direct Mode

Since DocumentDB is a distributed storage system, DocumentDB resources like collections and documents are partitioned across numerous machines and each partition is replicated for high availability. The logical to physical address translation is kept in a routing table which is also internally available as a resource.

In Gateway Mode, the DocumentDB gateway machines perform this routing, thereby allowing client code to be simple and compact. A client application issues requests to the DocumentDB gateway machines, which translate the logical URI in the request to the physical address of the backend node, and forward the request appropriately.  Conversely, in Direct Mode clients must maintain – and periodically refresh – a copy of this routing table, and then directly connect to the backend DocumentDB nodes.

Gateway Mode is supported on all SDK platforms and is the configured default.  If your application runs within a corporate network with strict firewall restrictions, Gateway Mode is the best choice since it uses the standard HTTPS port and a single endpoint. The performance tradeoff, however, is that Gateway Mode involves an additional network hop every time data is read or written to DocumentDB.   Because of this, Direct Mode offers better performance due to fewer network hops.

Direct Mode is currently supported only in the .NET SDK, but will be available in other platforms with subsequent SDK refreshes.  Read more about client connectivity options here.

Networking Tip #2 Connection Policy - Use TCP protocol for better performance

When leveraging Direct Mode, there are two protocol options available:

1. TCP
2. HTTPS

DocumentDB offers a simple and open RESTful programming model over HTTPS. Additionally, it offers an efficient TCP protocol which is also RESTful in its communication model and is available through the .NET client SDK. For best performance, use the TCP protocol when possible.

The Connectivity Mode is configured during the construction of the DocumentClient instance with the ConnectionPolicy parameter. If Direct Mode is used, the Protocol can also be set within the ConnectionPolicy parameter.

            var serviceEndpoint = new Uri("https://contoso.documents.net");
            var authKey = new "your authKey from Azure Mngt Portal";
            DocumentClient client = new DocumentClient(serviceEndpoint, authKey, 
            new ConnectionPolicy
            {
                ConnectionMode = ConnectionMode.Direct,
                ConnectionProtocol = Protocol.Tcp
            });

Because TCP is only supported in Direct Mode, if Gateway Mode is used, then the HTTPS protocol is always used to communicate with the Gateway and the Protocol value in the ConnectionPolicy is ignored.

Connection policy illustrated

Networking Tip #3: Call OpenAsync to avoid startup latency on first request

By default, the first request will have a higher latency because it has to fetch the address routing table. In order to avoid this startup latency on the first request, you should call OpenAsync() once during initialization as follows.

await client.OpenAsync();

Networking TIP #4: Collocate clients in same Azure region for performance

It is possible to experience high network latency between making a request to DocumentDB and receiving the response. This latency could likely vary from request to request depending on the route taken by the request from the client to the Azure datacenter boundary. The lowest possible latency will be achieved by ensuring the calling application is located within the same Azure region as the provisioned DocumentDB endpoint.

Deployment considerations illustrated

SDK USAGE

SDK Usage Tip #1: Use a singleton DocumentDB client for the lifetime of your application

Note that each DocumentClient instance is thread-safe and performs efficient connection management and address caching when operating in Direct Mode. To allow efficient connection management and better performance by DocumentClient, it is recommended to use a single instance of DocumentClient per AppDomain for the lifetime of the application.

SDK Usage Tip #2: Cache document and collection SelfLinks for lower read latency

In Azure DocumentDB, each document has a system-generated selfLink. These selfLinks are guaranteed to be unique and immutable for the lifetime of the document. Reading a single document using a selfLink is the most efficient way to get a single document. Due to the immutability of the selfLink, you should cache selfLinks whenever possible for best read performance.

Document document = await client.ReadDocumentAsync("/dbs/1234/colls/1234354/docs/2332435465");

Having said that, it may not be always possible for the application to work with a document’s selfLink for read scenarios; in this case, the next most efficient way to retrieve a document is to query by the document’s user provided Id property.  For example:

            IDocumentQuery<Document> query = (
                    from doc in client.CreateDocumentQuery(documentsLink)
                    where doc.Id == "myId"
                    select doc).AsDocumentQuery();

            Document myDocument = null;
            while (query.HasMoreResults)
            {
                FeedResponse<Document> res = await query.ExecuteNextAsync<Document>();
                if (res.Any())
                {
                    myDocument = res.Single();
                    break;
                }
            }

            return myDocument;

SDK Usage Tip #3: Tune page size for queries/read feeds for better performance

When performing a bulk read of documents using read feed functionality (i.e. ReadDocumentFeedAsync) or when issuing a DocumentDB SQL query, the results are returned in a segmented fashion if the result set is too large. By default, results are returned in chunks of 100 items or 1 MB, whichever limit is hit first.

In order to reduce the number of network round trips required to retrieve all applicable results, you can increase the page size using x-ms-max-item-count request header to up to 1000. In cases where you need to display only a few results, e.g., if your user interface or application API returns only ten results a time, you can also decrease the page size to 10 in order to reduce the throughput consumed for reads and queries.

You may also set the page size using the available DocumentDB SDKs.  For example:

            IQueryable<dynamic> authorResults = client.CreateDocumentQuery(documentsLink, 
                "SELECT p.Author FROM Pages p WHERE p.Title = 'About Seattle'", 
                new FeedOptions { MaxItemCount = 1000 });

WRAPPING UP

We hope you found one or more of these tips both useful and applicable to your usage of DocumentDB.  In part 2 of this blog series we will continue the discussion and cover indexing policies, throughput optimization and consistency levels.  In addition, we’d love to hear from you about the DocumentDB features and experiences you would find most valuable. 

Please submit your suggestions on the Microsoft Azure DocumentDB feedback forum. 

If you haven’t tried DocumentDB yet, then get started here.

As usual, you can find all of the source code available via github:

git clone git://github.com/Azure/azure-documentdb-java.git

As a fully open-sourced SDK, we love and welcome your contributions. Please follow the instructions provided in the Azure Projects Contributions Guidelines.

You can also get the latest binaries, ready to use within your project, via Maven:

<dependency> 
	<groupId>com.microsoft.azure</groupId> 
	<artifactId>azure-documentdb</artifactId> 
	<version>0.9.0</version> 
</dependency>

For more information on DocumentDB, Microsoft’s fully managed NoSQL document database service in the cloud, go here.

We have published a quick tutorial on how to create a Java web application on top of DocumentDB to help you get started.

If you need any help, please reach out to us on the Azure DocumentDB Developer Forums on MSDN or the developer forums on stack overflow.

Introduction

A question that we are frequently asked is “How do I design a multi-tenant application on top of Azure DocumentDB?” There are many answers to this question, and the best answer depends on your application’s particular scenario.

At a high-level, depending on the scale of your tenants you could choose to partition by database or collection. In cases where tenant data is smaller and tenancy numbers are higher – we suggest that you store data for multiple tenants in the same collection to reduce the overall resources necessary for your application. You can identify your tenant by a property in your document and issue filter queries to retrieve tenant-specific data. You can also use DocumentDB’s users and permissions to isolate tenant data and restrict access at a resource-level via authorization keys.

In cases where tenants are larger, need dedicated resources, or require further isolation - you can allocate dedicated collections or databases for tenants. In either case, DocumentDB will handle a significant portion of the operational burden for you as you scale-out your application’s data store.

In this article, we will discuss the concepts and strategies to help guide you towards a great design to fit your application’s requirements.

What is a Collection?

Before we dive deeper on partitioning data, it is important to understand what a collection is and what it isn’t.

As you may already know, a collection is a container for your JSON documents. Collections are also DocumentDB’s unit of partition and boundary for the execution of queries and transactions. Each collection provides a reserved amount of throughput. You can scale out your application, in terms of both storage and throughput, by adding more collections, and distributing your documents across them.

It is absolutely imperative to understand that collections are not tables. Collections do not enforce schema; in other words, you can store different types of documents with different schemas in the same collection. You can track different types of entities simply by adding a “type” attribute to your document.

Unlike some other document-databases, there is nothing wrong with having a lot of collections to achieve greater scale and performance. You may, however, want to re-use collections from a cost-savings perspective.

Sharding with DocumentDB

You can achieve near-infinite scale (in terms of storage and throughput) for your DocumentDB application by horizontally partitioning your data – a concept commonly referred to as sharding.

Sharding is a standard application pattern for achieving high scalability for large web applications. For applications that require the benefits of transactions, an application will need to partition its data carefully based on a key with each partition small enough to fit into a transaction domain (i.e. a collection). Sharded applications must be aware that data is spread across a number of partitions or transaction domains and need logic to select a partition and interact with it based on a shard-key.

A DocumentDB Application sharded across databases and collections.

Partitioning Scopes

The decision of whether to shard across multiple transactional domains depends on the scale of your application – as sharding generally involves additional data management logic in your application.

Hierarchical Resource Model under a Database Account

Let’s take a closer examination at the DocumentDB’s resource model and the various scopes that you could potentially partition your data across:

Placing all tenants in a single collection - This is generally a good starting point for most applications – e.g. whenever the total resource consumption across all of your tenants is well within the storage and throughput limitations of a single collection.

Security can be enforced at the application level simply by adding a tenant property inside your document and enforcing a tenant filter on all queries (e.g. SELECT * FROM collection c WHERE c.userId = “Andrew”). Security can be enforced at the DocumentDB level as well by creating a user for each tenant, assigning permissions to tenant data, and querying tenant data via the user’s authorization key.

Major benefits of storing tenant data within a single collection include reducing complexity, ensuring transactional support across application data, and minimizing financial cost of storage.

Placing tenants across multiple collections – In cases where your application needs more storage or throughput capacity than a single collection can handle, you can partition data across multiple collections. Fortunately, there is no need to set a limit on the size of your database and the number of collections. DocumentDB allows you to dynamically add collections and capacity as your application grows. You will, however, need to decide how the application will partition tenant data and route requests, which we’ll discuss in just a moment.

In addition to increased resource capacity, an advantage of partitioning data across multiple collections is the ability to allocate more resources for larger tenants over smaller tenants by placing them in less dense collections (e.g. you can place a tenant, who needs dedicated throughput, on to their own collection).

Placing tenants across multiple databases – For the most part, placing tenants across databases works fairly similar to placing tenants across collections. As shown in the resource model diagram above, the major distinction between DocumentDB collections and databases is that users and permissions are scoped at a database-level. In other words, each database has its own set of users and permissions – which you can use to isolate specific collections and documents.

Partitioning tenants by database may simplify user and permission management in scenarios where tenants require an extremely large set of users and permissions. When tenants are partitioned by database and the tenant leaves the application – the tenant’s data along with their users and permissions can all be discarded together simply by deleting the database.

Placing tenants across multiple database accounts – Likewise, placing tenants across database accounts works fairly similar to placing tenants across databases. The major distinction between database accounts and databases is that the master/secondary keys, DNS endpoints, and billing are scoped at a database account level.

Partitioning tenants by database account allows applications to maintain isolation between tenants in scenarios where tenants require access to their own database account keys (e.g. tenants require the ability to create, delete, and manage their own set of collections and users).

Common Sharding Patterns

If you’re partitioning data across multiple transactional domains, your application will need some sort of heuristic to partition its data and route requests to the correct partition. Some common heuristics for partitioning data include:

Range Partitioning

Partitions are assigned based on whether the partitioning key is inside a certain range. An example could be to partition data by timestamp or geography (e.g. zip code is between 30000 and 39999).

Range-Partitioning by Month

Lookup Partitioning

Partitions are assigned based on a lookup directory of discrete values that map to a partition. This is generally implemented by creating a lookup map that keeps track of which data is stored on which partition. You can cache look-up results to avoid making multiple round-trips. An example could be to partition data by user (e.g. partition G contains Harry, Ron, and Hermione and partition S contains Draco, Vincent, and Gregory) or country (e.g. partition Scandinavia contains Norway, Denmark, and Sweden)

Lookup Partitioning

Hash Partitioning

Partitions are based on the value of a hash function – allowing you to evenly distribute across n number of partitions. An example could be to partition data by the hash code % 3 of the tenant to evenly distribute tenants across 3 partitions.

Hash Partitioning

So which partitioning strategy is right for you? Range partitioning is generally useful in the context of dates, as it gives you an easy and natural mechanism for ageing out partitions. Lookup partitioning, on the other hand, allows you to group and organize unordered and unrelated sets of data in a natural way (e.g. group tenants by organization or states by geographic region). Hash partitioning is incredibly useful for load balancing when it is difficult to predict and manually balance the amount of data for particular groups or when range partitioning would cause the data to be undesirably clustered.

You don’t have to choose just one partitioning strategy either! A composite of these strategies can also be useful depending on the scenario – for example, a composite range-lookup partitioning may provide you both the manageability of range partitioning as well as the explicit control of lookup partitioning.

Composite Range-Lookup Partitioning

Fan-Out Operations

A common method for operating on data across multiple transactional domains is to issue a fan-out query, in which the application queries each partition in parallel and then consolidate the results.

Fan-Out Query

A primary architecture decision is when the fan-out occurs. Let’s use a news-feed aggregation timeline as an example; some common strategies for fan-out include:

Fan-Out on Write – The idea here is to avoid computation on reads and to do most of the processing on writes, making read time access extremely fast and easy. This may be a good decision if the timeline resembles something like Twitter – a roughly permanent, append-only, per-user aggregation of a set of source feeds. When an incoming event is recorded, it is stored in the source feed and then a record containing a copy is created for each timeline that it must be visible in.

Fan-Out on Read – This may be a good decision if the timeline resembles something like Facebook – in which the feed is temporal and needs to support dynamic features (such as real-time privacy checks and tailoring of content). When an event is recorded, it is only stored in the source feed. Every time a user requests their individual timeline, the system fan-out reads to all of the source feed the user has visibility into and aggregates the feeds together.

Managing Storage and Throughput

When a partition begins to fill up and run out of resources, it is time to spill-over or re-distribute data to another partition. This may occur when an outlying tenant is consuming more storage and/or throughput than expected, or the application is simply outgrowing the existing partitions. You will want to monitor and pick an appropriate threshold (e.g. 80% of storage consumed), based on the rate that which resources are consumed, to act upon to prevent the possibility of application failure.

Maintain enough headroom before having to spill-over/re-distribute data to avoid service-interruption.

One strategy to overcome storage-constraints may be to spill over incoming data in to a new collection. For example, spill-over may work well if your collections store highly temporal data and are partitioned by month or date. In this context, you could even consider pruning or archiving older collections as the age and become stale. It’s important to keep in mind that collections are the boundary for transactions and queries; you may have to fan-out your reads or writes if dealing with data across collections.

Another strategy to overcome storage and/or throughput constraints is to re-distribute your tenant data. For example, you could move an outlying tenant that consumes a lot more throughput than others to another collection. You may want to fan-out reads and/or writes during the migration process to avoid service interruption for the particular tenant.

Conclusion

DocumentDB has proven to scale for various multi-tenant scenarios here within Microsoft, including MSN which stores user data for Health & Fitness experiences (web and mobile) in a sharded database account. Check out the blog post on this use case!

For most things, the design for your application will depend heavily on its scenarios and data access patterns. Hopefully this article will serve as a great starting point to guide you in the right direction.

To learn how to get started with DocumentDB or for more information, please check out our website.

For more information on developing multi-tenant applications on Microsoft Azure in general, check out this great MSDN article.

A .NET developer might notice the omission of certain types they are used to. Most notable is probably the .NET DateTime type. So, how do we store, retrieve, and query using DateTime if the database doesn’t support these types natively?

Keep reading as that is the purpose of this post …

For the purposes of this post let us assume we’re working with the following sample POCO objects.

    public class Order
    {
        public string OrderNumber { get; set; }
        public DateTime OrderDate { get; set; }
        public DateTime ShipDate { get; set; }
        public double Total { get; set; }
    }

This is a simple demonstration of how an Order could be represented in .NET.
The order has two DateTime properties, OrderDate and ShipDate. For the purposes of this post we will be focusing primarily on these two properties.
The default format used by the DocumentDB SDK for handling DateTime objects is to convert them in to the ISO 8601 string format. Therefore, if we do nothing but pass our Order object to DocumentDB, as shown in the code snippet below,

var doc1 = client.CreateDocumentAsync(colLink, new Order { 
      OrderNumber = "09152014101",
      OrderDate = DateTime.UtcNow.AddDays(-30),
      ShipDate = DateTime.UtcNow.AddDays(-14), 
      Total = 113.39
});

The two .NET DateTime properties would be stored as a string similar to;

{
    "OrderDate": "2014-09-15T23:14:25.7251173Z",
    "ShipDate": "2014-09-30T23:14:25.7251173Z"
}

That string looks nice and readable like that, so why is this a problem?

DocumentDB has support for range based indexes on numeric fields allowing you to do range queries, (e.g. where field > 10 and field < 20). To avoid doing costly scans when doing range queries (records older than yesterday, or orders placed last week, or orders shipped today) on dates we need to convert the string representation of a Date to a number, so that we can use range indexes on these fields.

DocumentDB and JSON are neutral to how they represent DateTimes and you can use this neutrality to powerful effect to best suit your application’s needs.

This post introduces two methods of dealing with DateTime properties efficiently, but there are many more implementations that would treat Dates and Times efficiently.

For the rest of the post we will be treating DateTimes as epoch values, or the number of seconds since a particular date. We are using 1 January 1970 00:00 in this post, you can use a different starting point if you like depending on your data. I.e. if you are doing orders and your system only needs to deal with orders from today, then pick today as your starting point. Our fictitious system has lots of historical orders, so we need to go back in time a little.

Here is a simple .NET extension method for DateTime that will do this conversion for us;

public static class Extensions
{
    public static int ToEpoch(this DateTime date)
    {
        if (date == null) return int.MinValue;
        DateTime epoch = new DateTime(1970, 1, 1);
        TimeSpan epochTimeSpan = date - epoch;
        return (int)epochTimeSpan.TotalSeconds;
    }
}

Now how do you use this in your application?

Well there are two ways to proceed, and you can choose the way that best suits the needs of your application.

The first way is store a number field that represents the DateTime instead of the DateTime itself.

The easiest way to do this is to implement a custom serializer & deserializer for dealing with JSON. I’m going to show doing this with JSON.NET by implementing a customer JsonConverter that changes the default behavior of a DateTime property.

To do this we define a class that extends the JsonConverter abstract class and overrides the ReadJson and WriteJson methods.

public class EpochDateTimeConverter : JsonConverter
{
    ...
}

Below is the WriteJson implementation that takes  in  a .NET DateTime and outputs a number using the same ToEpoch() extension method we created above.

public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
{
    int seconds;
    if (value is DateTime)
    {
        DateTime dt = (DateTime)value;
        if (!dt.Equals(DateTime.MinValue))
            seconds = dt.ToEpoch();
        else
            seconds = int.MinValue;
    }
    else
    {
        throw new Exception("Expected date object value.");
    }

    writer.WriteValue(seconds);
}

We also have the reverse, the ReadJson method, which will be used during serialization from JSON back in to .NET. This method takes in a number representing the number of seconds since Jan 1 1970 UTC and returns the .NET DateTime equivalent.

public override object ReadJson(JsonReader reader, Type type, object value, JsonSerializer serializer)
{
    if (reader.TokenType == JsonToken.None || reader.TokenType == JsonToken.Null) 
        return null;

    if (reader.TokenType != JsonToken.Integer)
    {
        throw new Exception(
            String.Format("Unexpected token parsing date. Expected Integer, got {0}.",
            reader.TokenType));
    }

    int seconds = (int)reader.Value;
    return new DateTime(1970, 1, 1).AddSeconds(seconds);
}

To use this in an application we need to decorate our DateTime properties with the JsonConverter attribute. Now, when these properties are serialized / deserialized Json.NET knows not to work with its default but to use our custom code instead.

    public class Order
    {
        public string OrderNumber { get; set; }

        [JsonConverter(typeof(EpochDateTimeConverter))]
        public DateTime OrderDate { get; set; }

        [JsonConverter(typeof(EpochDateTimeConverter))]
        public DateTime ShipDate { get; set; }

        public double Total { get; set; }
    }

The result after serialization is now a number in JSON and a number being stored in DocumentDB.

{
    "OrderDate": 1408318702,
    "ShipDate": 1408318702 
}

To do an efficient range queries on a numeric field in DocumentDB we have to define a Range Index on the path containing our numeric field, when we create the DocumentCollection.

The example below shows creating a DocumentCollection with a custom IndexPolicy. We use a Numeric Precision of 7 bytes for this range index because we are dealing with numbers in the billions. For a smaller range of numbers it would be sufficient to use smaller precision levels.

var collection = new DocumentCollection
{
    Id = id
};

//set the default IncludePath to set all properties in the document to have a Hash index
collection.IndexingPolicy.IncludedPaths.Add(new IndexingPath
{
    IndexType = IndexType.Hash,
    Path = "/",
});

//now define two additional paths in Order that we know we want to do Range based queries on
collection.IndexingPolicy.IncludedPaths.Add(new IndexingPath
{
    IndexType = IndexType.Range,
    Path = "/\"OrderDate\"/?",
    NumericPrecision = 7
});

collection.IndexingPolicy.IncludedPaths.Add(new IndexingPath
{
    IndexType = IndexType.Range,
    Path = "/\"ShipDate\"/?",
    NumericPrecision = 7
});

collection = client.CreateDocumentCollectionAsync(dbLink, collection).Result;

Once this is in place, doing a query on a DateTime property is as easy as;

//convert "7 days ago" to epoch number using our ToEpoch extension method for DateTime
int epocDateTime DateTime.UtcNow.AddDays(-7).ToEpoch();

//build up the query string
string sql = string.Format("SELECT * FROM Collection c WHERE c.OrderDate > {0}", 
    epocDateTime);

//execute the query and get the results in a List
var orders = client.CreateDocumentQuery<Order>(col.SelfLink, sql).ToList();

That’s one approach, and it works very efficiently. The downside however is that you lose the human readable date string in your database. Should another application connect to our database the custom deserializer won’t necessarily be run and the value returned is now difficult to deal with because not many humans can do an epoch conversion in their heads (I certainly can’t).

The second way to implement this is to preserve the readable DateTime field but add an additional field to your document which stores the numeric representation of the DateTime in addition to the string representation.

To do this, we can create a new custom type that looks like this;

public class DateEpoch
{
   public DateTime Date { get; set; }
   public int Epoch
   {
       get
       {
           return (this.Date.Equals(null) || this.Date.Equals(DateTime.MinValue))
               ? int.MinValue
               : this.Date.ToEpoch();
        }
    }
}

Now change the two DateTime properties of the Order object to this new type like this;

public class Order
{
    public string OrderNumber { get; set; }
    public DateEpoch OrderDate { get; set; }
    public DateEpoch ShipDate { get; set; }
    public double Total { get; set; }
}

With this in place, when you now pass your object to DocumentDB you will end up with JSON that looks something like this;

{
    "OrderDate": {
        "Date": "2014-09-15T23: 14: 25.7251173Z",
        "Epoch": 1408318702
    },
    "ShipDate": {
        "Date": "2014-09-30T23: 14: 25.7251173Z",
        "Epoch": 1408318702
    }
}

As you did with the first technique you have to define a custom IndexPolicy on your DocumentCollection except this time we add the range path on the Epoch value only. You could exclude the date string path from the index if you like but keeping the default hash index still allows for equality operations if you want to do that.

var collection = new DocumentCollection
{
    Id = id
};

//set the default IncludePath to set all properties in the document to have a Hash index
collection.IndexingPolicy.IncludedPaths.Add(new IndexingPath
{
    IndexType = IndexType.Hash,
    Path = "/",
});

//now define two additional paths in Order2 that we know we want to do Range based queries on
collection.IndexingPolicy.IncludedPaths.Add(new IndexingPath
{
    IndexType = IndexType.Range,
    Path = "/\"OrderDate\"/\"Epoch\"/?",
    NumericPrecision = 7
});

collection.IndexingPolicy.IncludedPaths.Add(new IndexingPath
{
    IndexType = IndexType.Range,
    Path = "/\"ShipDate\"/\"Epoch\"/?",
    NumericPrecision = 7
});

//could also exclude the Date portion of the dates in Order2 as we're never going to 
//index on these, but will leave these there because they're still indexed with a hash 
//so you could do equality operations on them.

collection = client.CreateDocumentCollectionAsync(dbLink, collection).Result;

Now to query with this approach you could execute the following LINQ query, I chose to demonstrate LINQ here and not SQL as in the previous example, because this is another advantage of this approach.

var orders = from o in client.CreateDocumentQuery<Order2>(col.SelfLink)
    where o.OrderDate.Epoch >= DateTime.Now.AddDays(-7).ToEpoch()
    select o;

Or, you can choose the following LINQ Lambda syntax if you favor that;

var orders2 = client.CreateDocumentQuery<Order2>(col.SelfLink)
    .Where(o => o.OrderDate.Epoch >= DateTime.UtcNow.AddDays(-7).ToEpoch())
    .ToList();

And of course the SQL syntax we used earlier would also be valid and give the same result and is what you would use when LINQ was not available to you;

string sql = String.Format("SELECT * FROM c WHERE c.OrderDate.Epoch >= {0}", 
                 DateTime.UtcNow.AddDays(-7).ToEpoch());

This second approach has two main advantages over the first. Firstly it does not rely on a custom serialization technique for specific tool like JSON.NET so it can be used with other JSON serializers or with other languages beside just .NET. This technique would work equally well in say Node.JS or in Python. Secondly because we keep the human readable DateTime value as a string if another application queries your data, humans will still have a readable version of the date to work with.

This approach requires more storage and results in slightly larger documents as a result, but if you are not sensitive about the storage costs or the size of the document being too big then I favor this approach over the first for the benefits listed above.

And that’s it, DateTime properties in DocumentDB. Done

If you would like the sample code for this blog post you can download it from here

To get started with Azure DocumentDB head over to the service documentation page on azure.com  => https://azure.microsoft.com/en-us/documentation/services/documentdb/ where you can find everything you need to get up & running.

• Bulk add Documents – Upload multiple existing JSON documents via Document Explorer
• Query syntax highlighting – Keyword and value highlighting in Query Explorer
• Improved query experience – Edit and re-execute queries without closing the results blade

Keep reading for additional information on each of these new features or get started now with DocumentDB

Add Documents

Document Explorer allows you to easily create, edit, and delete JSON documents stored in DocumentDB and is available from any of the DocumentDB account, database or collection blades:

With this release, Document Explorer now supports upload of multiple existing JSON documents. Simply open Document Explorer from any of the aforementioned blades and click the “Add Document” command:

A new blade will open. Click the browse button to open a file explorer window and select 1 or more JSON documents to upload. Note that Document Explorer currently supports up to 50 JSON documents per upload operation:

Once you’re satisfied with your selection, click the upload button. The documents will automatically be added to the Document Explorer grid and results will be displayed as the upload operation progresses:

Once the operation has completed, you can select up to another 50 documents to upload.

Query Explorer – Syntax Highlighting

Query Explorer allows you to author, edit, and run DocumentDB SQL queries against any of your DocumentDB collections. Similar to Document Explorer, Query Explorer is available from any of the DocumentDB account, database, and collection blades:

In this release, we’ve enabled basic keyword and value highlighting within Query Explorer to improve the query authoring experience :

Query Explorer – Rerun queries

Finally, we’ve modified the Query Explorer blade so that you can run, edit and re-run queries without having to close the results blade:

As always, we’d love to hear from you about the DocumentDB features and experiences you would find most valuable within the Azure portal.

Please submit your suggestions on the Microsoft Azure DocumentDB feedback forum.

If you haven’t tried DocumentDB yet, then get started here.

Enjoy!

Stephen Baron
Program Manager

We’ve released a number of great enhancements to further improve the DocumentDB management experience.  Our October 23^rd portal update lights up the following new capabilities through https://portal.azure.com:

• Document CRUD operations – create, edit and delete documents
• Document system properties – view system properties for each document
• Document filtering and refresh – filter and refresh results within Document Explorer
• Query Explorer – author and run DocumentDB SQL queries

Keep reading for some additional information on each of these new features!

Document CRUD operations

Document Explorer has been enhanced such that you can create, edit and delete documents.  To create a document, simply click the Create Document command and a minimal JSON snippet will be provided:

Note that if you choose to not provide an id, Document Explorer will automatically generate a GUID as the id value. 

Once I click save, the document is updated to reflect the supplied (or generated) id:

Additionally, the document is added to the bottom of the document list in Document Explorer:

To edit an existing document, simply select it in Document Explorer, edit the document as you see fit, and click the Save command:

Likewise, you can delete a document by selecting it, clicking the Delete command and then confirming the delete (after confirming, the document will immediately be removed from the Document Explorer list):

If you’re editing a document and decide that you want to discard the edits, simply click the discard command, confirm the discard action, and the previous state of the document will be reloaded:

Note that Document Explorer will validate that the document contains valid JSON:

And will also prevent you from saving a document with invalid JSON content:

Document System Properties

We've also added a properties command to Document Explorer which allows you to view the system properties of the currently loaded document:

Note that the timestamp (_TS) property is internally represented as epoch time but in the portal experience we've converted the display value to a human readable GMT format.

Document Explorer Filter and Refresh Support

Document Explorer now supports filtering the currently loaded set of documents by the id property. Simply type in the filter box:

and the results in the Document Explorer list will be filtered based on your criteria:

 Finally, we've added a Refresh command to allow you to easily refresh the documents displayed in Document Explorer:

 Query Explorer

We’re very happy to introduce a new Query Explorer experience which allows you author and run DocumentDB SQL queries.

You can launch Query Explorer from any of the DocumentDB Account, Database, or Collection blades. 
A default query of SELECT * FROM c is provided in the Query Editor:

You can accept the default query or construct your own and then click the Run command to view the results:

By default, Query Explorer will return results in sets of 100. 
If your query produces more than 100 results, simply use the Next page and Previous page commands to navigate through the result set:

Successful queries will provide information such as the request charge, the set of results currently being shown and whether or not there are more results (which can then be accessed via the Next page command in the results pane):

Likewise, if a query completes with errors, the portal will display a list of errors which can help with troubleshooting efforts:

As always, we’d love to hear from you about the DocumentDB features and experiences you would find most valuable within the Azure portal.  Please submit your suggestions on the Microsoft Azure DocumentDB feedback forum.  If you haven’t tried DocumentDB yet, then get started here.

Enjoy!

Stephen Baron
Program Manager