-
-
Notifications
You must be signed in to change notification settings - Fork 198
Tutorial
The purpose of this tutorial is to understand how to save some custom objects to the documents store, create some indexes and execute some queries. This assumes you have some good knowledge of C# and are familiar with document databases concepts.
The full source of the tutorial can be found in the source code in the samples directory here: https://github.com/sebastienros/yessql/tree/master/samples/YesSql.Samples.Hi
The model which will be used during this tutorial is made of a single class BlogPost. Here is the complete class:
public class BlogPost
{
public string Title { get; set; }
public string Author { get; set; }
public string Content { get; set; }
public DateTime PublishedUtc { get; set; }
public string[] Tags { get; set; }
}This class contains different content types in order to demonstrate that we don't have to care about them during the modeling process. There is no constraint on them. As a document, it's a root aggregate, which means any related object will be persisted as only one document. In YesSql a document will be materialized as a single database record in the Document table.
A store is just a simple relational database instance. It can be any type of SQL database, as long as Dapper supports it. The tutorial will use SqLite but you can switch it to any one you want.
A store is represented by the Store class. An instance of Store should be unique per application, a singleton. This is a common practice in database management. If you have ever used an ORM like NHibernate or Entity Framework then it will be familiar. It depends on each application to define what strategy is used to access this singleton (DI, static accessor, ...). This tutorial is based on single method call, which means it won't deal with this particular aspect.
var store = await StoreFactory.CreateAndInitializeAsync(
new Configuration()
.UseSqLite(@"Data Source=yessql.db;Cache=Shared")
.SetTablePrefix("Hi")
);In this example the store is initialized using a connection string to a local Sqlite database named yessql.db.
The store will behave as a factory for database transactions. In YesSql they are called sessions.
// creating a blog post
var post = new BlogPost
{
Title = "Hello YesSql",
Author = "Bill",
Content = "Hello",
PublishedUtc = DateTime.UtcNow,
Tags = new[] {"Hello", "YesSql"}
};
// saving the post to the database
await using(var session = store.CreateSession())
{
session.Save(post);
await session.SaveChangesAsync();
}To save the changes, like a new document, call await session.SaveChangesAsync() explicitly. A call to await session.CancelAsync() can be used to prevent the current changes from being committed.
// loading an single blog post
await using(var session = store.CreateSession())
{
var p = await session.Query<BlogPost>().FirstOrDefaultAsync();
Console.WriteLine(p.Title); // > Hello YesSql
}Updating a document and saving it back to the store should be done as part of the same session.
// loading an existing blog post
await using(var session = store.CreateSession())
{
var p = await session.Query<BlogPost>().FirstOrDefaultAsync();
// this change will be saved back into the same store document
p.Title = "A new title";
session.Save(p);
await session.SaveChangesAsync(); // or: await session.FlushAsync();
}Using the Query method doesn't give access to the inner properties of the documents themselves, which is a major limitation for most real scenarios. To do such queries, you will need to create some dedicated indexes.
- Mapped indexes, to do elementary queries on document properties
- Reduced indexes, for grouping and doing queries on aggregated property values
A mapped index is represented as a class inheriting from MapIndex. Here is an example which will store the Author property of the BlogPost class.
public class BlogPostByAuthor : MapIndex
{
public string Author { get; set; }
}Indexes have to be described in IIndexProvider implementations. Here is one registering BlogPostByAuthor by inheriting from IndexProvider<T>.
public class BlogPostIndexProvider : IndexProvider<BlogPost>
{
public override void Describe(DescribeContext<BlogPost> context)
{
// for each BlogPost, create a BlogPostByAuthor index
context.For<BlogPostByAuthor>().Map(blogPost => new BlogPostByAuthor { Author = blogPost.Author });
}
}This class will tell the system how to construct the indexes from an existing BlogPost object. Right now there is only one index defined, but several could be described in the same provider.
Then the provider is registered in the system like this:
store.RegisterIndexes<BlogPostIndexProvider>();
Queries are executed directly on the map index. You can use either QueryIndex<TIndex>() to query the index itself, or Query<T, TIndex>() on an ISession instance to retrieve the associated documents.
// loading blog posts by author
await using (var session = store.CreateSession())
{
var ps = await session.Query<BlogPost, BlogPostByAuthor>(x => x.Author.StartsWith("B")).ListAsync();
foreach (var p in ps)
{
Console.WriteLine(p.Author); // > Bill
}
}This example demonstrates how to use the index to query BlogPost by their Author property.
Map/Reduce indexes are useful to construct aggregated information from multiple objects. With a map index, one index entry is related to only one object, whereas with a map/reduced, an index entry will represent some information for a set of objects.
Let's say we want to compute some indexes representing how many 'BlogPost' are published for a specific day, and also keep a trace of those posts. Here is a BlogPostByDay index class inheriting from ReduceIndex.
public class BlogPostByDay : ReduceIndex
{
public virtual string Day { get; set; }
public virtual int Count { get; set; }
}This index then needs to be described in an index provider. The only difference is that on top of a map function, it also need to define how to group and also reduce those results. Ultimately a delete function tells YesSql what to do with the index when a related object is deleted, the opposite of reducing the index.
// for each BlogPost, aggregate in an exiting BlogPostByDay
context.For<BlogPostByDay, string>()
.Map( blogPost => new BlogPostByDay {
Day = blogPost.PublishedUtc.ToString("yyyyMMdd"),
Count = 1
})
.Group( blogPost => blogPost.Day )
.Reduce( group => new BlogPostByDay {
Day = group.Key,
Count = group.Sum(p => p.Count)
})
.Delete( (index, map) => {
index.Count -= map.Sum(x => x.Count);
// if Count == 0 then delete the index
return index.Count > 0 ? index : null;
});Here are some examples of how to use the newly created index:
// loading blog posts by day of publication
await using (var session = store.CreateSession())
{
var ps = await session.Query<BlogPost, BlogPostByDay>(x => x.Day == DateTime.UtcNow.ToString("yyyyMMdd")).ListAsync();
foreach (var p in ps)
{
Console.WriteLine(p.PublishedUtc); // > [Now]
}
}
// counting blog posts by day
await using (var session = store.CreateSession())
{
var days = await session.QueryIndex<BlogPostByDay>().ListAsync();
foreach (var day in days)
{
Console.WriteLine(day.Day + ": " + day.Count); // > [Today]: 1
}
}YesSql ReduceIndex support one record spawning multiple index record, also updating count numbers correctly when updating a document, such as, changeing the category of an article. Demo code: https://github.com/sebastienros/yessql/issues/431