Posts tagged with 'couchbase'

This is a repost that originally appeared on the Couchbase Blog: SQL to JSON Data Modeling with Hackolade.

SQL to JSON data modeling is something I touched on in the first part of my "Moving from SQL Server to Couchbase" series. Since that blog post, some new tooling has come to my attention from Hackolade, who have recently added first-class Couchbase support to their tool.

In this post, I’m going to review the very simple modeling exercise I did by hand, and show how IntegrIT’s Hackolade can help.

I’m using the same SQL schema that I used in the previous blog post series; you can find it on GitHub (in the SQLServerDataAccess/Scripts folder).

Review: SQL to JSON data modeling

First, let’s review, the main way to represent relations in a relational database is via a key/foreign key relationship between tables.

When looking at modeling in JSON, there are two main ways to represent relationships:

  • Referential - Concepts are given their own documents, but reference other document(s) using document keys.

  • Denormalization - Instead of splitting data between documents using keys, group the concepts into a single document.

I started with a relational model of shopping carts and social media users.

Relational model of SQL before moving to JSON

In my example, I said that a Shopping Cart - to - Shopping Cart Items relationship in a relational database would probably be better represented in JSON by a single Shopping Cart document (which contains Items). This is the "denormalization" path. Then, I suggested that a Social Media User - to - Social Media User Update relationship would be best represented in JSON with a referential relationship: updates live in their own documents, separate from the user.

This was an entirely manual process. For that simple example, it was not difficult. But with larger models, it would be helpful to have some tooling to assist in the SQL to JSON data modeling. It won’t be completely automatic: there’s still some art to it, but the tooling can do a lot of the work for us.

Starting with a SQL Server DDL

This next part assumes you’ve already run the SQL scripts to create the 5 tables: ShoppingCartItems, ShoppingCart, FriendBookUsers, FriendBookUpdates, and FriendBookUsersFriends. (Feel free to try this on your own databases, of course).

The first step is to create a DDL script of your schema. You can do this with SQL Server Management Studio.

First, right click on the database you want. Then, go to "Tasks" then "Generate Scripts". Next, you will see a wizard. You can pretty much just click "Next" on each step, but if you’ve never done this before you may want to read the instructions of each step so you understand what’s going on.

Generate DDL script from SQL Management Studio

Finally, you will have a SQL file generated at the path you specified.

This will be a text file with a series of CREATE and ALTER statements in it (at least). Here’s a brief excerpt of what I created (you can find the full version on Github).

CREATE TABLE [dbo].[FriendBookUpdates](
	[Id] [uniqueidentifier] NOT NULL,
	[PostedDate] [datetime] NOT NULL,
	[Body] [nvarchar](256) NOT NULL,
	[UserId] [uniqueidentifier] NOT NULL,
	[Id] ASC


-- etc...

By the way, this should also work with SQL Azure databases.

Note: Hackolade works with other types of DDLs too, not just SQL Server, but also Oracle and MySQL.

Enter Hackolade

This next part assumes that you have downloaded and installed Hackolade. This feature is only available on the Professional edition of Hackolade, but there is a 30-day free trial available.

Once you have a DDL file created, you can open Hackolade.

In Hackolade, you will be creating/editing models that correspond to JSON models: Couchbase (of course) as well as DynamoDB and MongoDB. For this example, I’m going to create a new Couchbase model.

Create a new Couchbase model in Hackolade

At this point, you have a brand new model that contains a "New Bucket". You can use Hackolade as a designing tool to visually represent the kinds of documents you are going to put in the bucket, the relationships to other documents, and so on.

We already have a relational model and a SQL Server DDL file, so let’s see what Hackolade can do with it.

Reverse engineer SQL to JSON data modeling

In Hackolade, go to Tools → Reverse Engineer → Data Definition Language file. You will be prompted to select a database type and a DDL file location. I’ll select "MS SQL Server" and the "script.sql" file from earlier. Finally, I’ll hit "Ok" to let Hackolade do its magic.

SQL to JSON data modeling reverse engineering with Hackolade

Hackolade will process the 5 tables into 5 different kinds of documents. So, what you end up with is very much like a literal translation.

SQL to JSON data modeling reverse engineering with Hackolade result

This diagram gives you a view of your model. But now you can think of it as a canvas to construct your ultimate JSON model. Hackolade gives you some tools to help.


For instance, Hackolade can make suggestions about denormalization when doing SQL to JSON data modeling. Go to Tools→Suggest denormalization. You’ll see a list of document kinds in "Table selection". Try selecting "shoppingcart" and "shoppingcartitems". Then, in the "Parameters" section, choose "Array in parent".

Suggest denormalization in Hackolade

After you do this, you will see that the diagram looks different. Now, the items are embedded into an array in shoppingcart, and there are dashed lines going to shoppingcartitems. At this point, we can remove shoppingcartitems from the model (in some cases you may want to leave it, that’s why Hackolade doesn’t remove it automatically when doing SQL to JSON data modeling).

Remove excess table in Hackolade

Notice that there are other options here too:

  • Embedding Array in parent - This is what was demonstrated above.

  • Embedding Sub-document in child - If you want to model the opposite way (e.g. store the shopping cart within the shopping cart item).

  • Embedding Both - Both array in parent and sub-document approach.

  • Two-way referencing - Represent a many-to-many relationship. In relational tables, this is typically done with a "junction table" or "mapping table"

Also note cascading. This is to prevent circular referencing where there can be a parent, child, grandchild, and so on. You select how far you want to cascade.

More cleanup

There are a couple of other things that I can do to clean up this model.

  • Add a 'type' field. In Couchbase, we might need to distinguish shoppingcart documents from other documents. One way to do this is to add a "discriminator" field, usually called 'type' (but you can call it whatever you like). I can give it a "default" value in Hackolade of "shoppingcart".

  • Remove the 'id' field from the embedded array. The SQL table needed this field for a foreign key relationship. Since it’s all embedded into a single document, we no longer need this field.

  • Change the array name to 'items'. Again, since a shopping cart is now consolidated into a single document, we don’t need to call it 'shoppingcartitems'. Just 'items' will do fine.

Clean up JSON data model in Hackolade


A model like this can be a living document that your team works on. Hackolade models are themselves stored as JSON documents. You can share with team members, check them into source control, and so on.

You can also use Hackolade to generate static documentation about the model. This documentation can then be used to guide the development and architecture of your application.

Go to File → Generate Documentation → HTML/PDF. You can choose what components to include in your documentation.


Hackolade is a NoSQL modeling tool created by the IntegrIT company. It’s useful not only in building models from scratch, but also in reverse engineering for SQL to JSON data modeling. There are many other features about Hackolade that I didn’t cover in this post. I encourage you to download a free trial of Hackolade today. You can also find Hackolade on Twitter @hackolade.

If you have questions about Couchbase Server, please ask away in the Couchbase Forums. Also check out the Couchbase Developer Portal for more information on Couchbase for developers. Always feel free to contact me on Twitter @mgroves.

This is a repost that originally appeared on the Couchbase Blog: C# Tuples: New C# 7 language feature.

C# tuples are a new feature of C# 7. I’m going to show you the basics of how C# tuples work. I’m also going to mix in a little Couchbase to show tuples in action. However, if you don’t want to install Couchbase just to play around with tuples, don’t worry, you will still be able to follow along.

Note: If you’ve been using C# for a while, you might remember the Tuple Class that was introduced in .NET 4. That class still exists, but it is not the same thing as the new tuple feature of C#.

What are C# tuples?

A "tuple" is a name for a mathematical concept that is just a list of elements. In the LISP family of languages, coding is built almost entirely around the idea that everything is a list. C# once again borrows the kernel of an idea from the functional programming world and integrates it into a non-functional language. So, we get C# tuples (check out the original C# tuple proposal by Mads Torgersen for more details and background).

Remember anonymous types?

But, to make it simple, let’s consider something you may already be familiar with in C#, an anonymous type. To review, you can instantiate a new object without specifying a type:

var myObject = new { Foo = "bar", Baz = 123 };

Behind the scenes, there actually is a type that inherits from the base Object type, but generally speaking, we only deal with the object, not its type.

Additionally, I can’t return an anonymous type from a method, or pass an anonymous type as a parameter without losing the type information in the process.

private object GetAnonymousObject()
    return new {Foo = "bar", Baz = 123};

private void AnotherMethod()
    var obj = GetAnonymousObject();
    Console.WriteLine(obj.Foo); // compiler error :(

They are useful, certainly, but I generally refer to these as anonymous objects as I use them, for these reasons.

What’s this got to do with C# tuples?

I think of C# tuples as richer anonymous types. They are a way to create a "class" on the fly without actually defining a class. The syntax for tuples is to simply put parenthesis around a comma separated list of types and names. A tuple literal is just a comma separated list of literals also surrounded by parenthesis. For instance:

(string FirstName, string LastName) myTuple = ("Matt", "Groves");

Console.WriteLine(myTuple.FirstName); // no compiler error :)
Console.WriteLine(myTuple.LastName);  // no compiler error :)

Note: Right now I’m preferring PascalCase for tuple properties. I don’t know if that’s the official guideline or not, but it "feels" right to me.

C# tuples in action

I put tuples to work in a simple console app that interacts with Couchbase.

I created a BucketHelper class that is a very simple facade over the normal Couchbase IBucket. This class has two methods: one to get a document by key and return a tuple, and one to insert a tuple as a document.

public class BucketHelper
    private readonly IBucket _bucket;

    public BucketHelper(IBucket bucket)
        _bucket = bucket;

    public (string Key, T obj) GetTuple<T>(string key)
        var doc = _bucket.Get<T>(key);
        return (doc.Id, doc.Value);

    public void InsertTuple<T>((string Key, T obj) tuple)
        _bucket.Insert(new Document<T>
            Id = tuple.Key,
            Content = tuple.obj

To instantiate this helper, you just need to pass an IBucket into the constructor.

Tuple as a return type

You can then use the GetTuple method to get a document out of Couchbase as a tuple.

var bucketHelper = new BucketHelper(bucket);

(string key, Film film) fightClub = bucketHelper.GetTuple<Film>("film-001");

The tuple will consist of a string (the document key) and an object of whatever type you specify. The document content is JSON and will be serialized to a C# object by the .NET SDK.

Also, notice that the name of the tuple properties don’t have to match. I used obj in BucketHelper but I used film when I called GetTuple<Film>. The types do have to match, of course.

Tuple as a parameter type

I can also go the other way and pass a tuple as a parameter to InsertTuple.

string key = Guid.NewGuid().ToString();
Film randomFilm = GenerateRandomFilm();
bucketHelper.InsertTuple((key, randomFilm));

The GenerateRandomFilm method returns a Film object with some random-ish values (check out the GitHub source for details). A tuple of (string, Film) is passed to InsertTuple. The Couchbase .NET SDK takes it from there and inserts a document with the appropriate key/value.

Running the console app, you should get an output that looks something like this:

C# tuples sample console output

Note that the Couchbase .NET SDK at this time doesn’t have any direct tuple support, and it may not ever need it. This code is simply to help demonstrate C# tuples. I would not recommend using the BucketHelper as-is in production.

TUH-ple or TOO-ple?

I seem to remember my professor(s) pronouncing it as "TOO-ple", so that’s what I use. Like the hard-G / soft-G debate of "GIF", I’m sure there are those who think this debate is of the utmost importance and are convinced their pronunciation is the one true way. But, both are acceptable.

If you have questions about tuples, I’d be happy to help. You can also contact me at Twitter @mgroves or email me

If you have questions about the Couchbase .NET SDK that I used in this post, please ask away in the Couchbase .NET Forums. Also check out the Couchbase Developer Portal for more information on the .NET SDK and Couchbase in general.

This is a repost that originally appeared on the Couchbase Blog: ASP.NET with NoSQL Workshop.

I delivered an ASP.NET with NoSQL workshop at the recent Indy.Code() conference in Indianapolis. I had a lot of fun at this conference, and I recommend you go next year. If you were unable to attend, don’t worry, because I’ve got the next best thing for you: all the material that I used in my workshop.

ASP.NET Workshop in 4 parts

This workshop contained four main parts:

  • Install a NoSQL database (Couchbase Server)

  • Interact with Couchbase Server (using both the Web Console and the .NET (or .NET Core) SDK)

  • Create a RESTful API using ASP.NET (or ASP.NET Core) WebAPI

  • Consume the RESTful API with an Angular frontend

Try it yourself

If you’d like to try it yourself, the ASP.NET with NoSQL Workshop materials are available on GitHub. Each part of the workshop contains a PPT and PDF file for you to follow along. Also, the "completed" version of each workshop is available.

If you get stuck or have any questions, please ask away in the Couchbase .NET Forums. Also check out the Couchbase Developer Portal for more information on the .NET SDK and Couchbase in general.

You can also contact me at Twitter @mgroves.

This is a repost that originally appeared on the Couchbase Blog: Data structures with Couchbase and .NET (video).

In February, I wrote a blog about using data structures with .NET (and .NET Core): List, Queue, and Dictionary.

Now, I’ve created a video to show the same concepts in action.

How to use Couchbase Data Structures with .NET

The source code used in this video is available on GitHub. Note that the source code uses .NET Core, but this should work just the same in .NET.

Thanks for watching!

If you have any questions about Couchbase and .NET, please ask away in the Couchbase .NET Forums. Also check out the Couchbase Developer Portal for more information on the .NET SDK and Couchbase in general.

You can also contact me at Twitter @mgroves.

This is a repost that originally appeared on the Couchbase Blog: Hyper-V: How to run Ubuntu (or any Linux) on Windows.

I recently needed to install a Linux distro (Ubuntu being my favorite) in Hyper-V on Windows 10. I needed to do this because some internal builds of Couchbase were temporarily broken on Windows, but I still needed to use the latest builds. I’d never used Hyper-V to do this before, but it wasn’t that difficult. And the best part is that it comes with Windows: I don’t have to install VirtualBox or VMWare or anything like that.

Download Ubuntu

There are lots of great Linux distros out there, and Couchbase Server can be run on a variety of them. However, Ubuntu Desktop is my go-to.

The first thing I did was to download an Ubuntu Desktop ISO. I know that Couchbase support for Ubuntu 16 is coming, but for now I want to stick to Ubuntu 14. So, I downloaded an ISO of 14.04.5 (aka Trusty Tahr).

Make sure Hyper-V is enabled

Check to make sure that you have Hyper-V enabled on Windows.

First, open Control Panel. Next, go to Programs. Then, click "Turn Windows features on or off". Finally, locate Hyper-V and click the checkbox (if it isn’t already checked).

Enable Hyper-V feature in Windows

You may also need to enable virtualization in the BIOS settings on your computer. The computer I’m using has it turned on by default. I wish I could give you instructions on how to do this, but it’s going to vary based on your BIOS.

Create a Hyper-V Virtual Switch

When connecting the virtual machine to a network, you’ll need to select a virtual switch. If you haven’t done this before, you’ll need to create one.

First, click "Virtual Switch Manager", then select "External". Click "Create Virtual Switch". Finally, give the switch a name. (You also need to choose an external network; in my case I only have one). Hit "Apply".

Create Hyper-V virtual switch

I wanted my machine to be connected to my home network, so I chose External. If you use External, it will connect to your network as a separate machine. After I create the machine (in the next section) it will appear on my router as it’s own machine:

Hyper-V machine attached to my network

Create a new Hyper-V Virtual Machine

Now you’re ready to create the virtual machine that will be running Ubuntu.

First, open the Hyper-V Manager from the Start menu. Then, click "New" and then "Virtual Machine". This will start a wizard.

First, give your machine a name (like "UbuntuForCouchbase"). Optionally, you can choose where to store this machine, or use the default directory.

Next, you must choose Generation 1 or Generation 2. I used Generation 1, but Ubuntu 14+ should work on Generation 2 as well.

After that, specify how much memory to allocate to the machine. I have a lot of RAM on my desktop, so I gave it 8192mb.

Next, select the switch that was created in the previous section.

Then, setup the virtual hard disk to your liking. You can choose the location and size of the disk. I don’t need very much, so I went with 60gb.

Finally, you need to select an operating system. I’ll choose "Install an operating system from a bootable CD/DVD-ROM", and then "Image file", and find the Ubuntu ISO that I downloaded.

Click "Next", view the summary, and click "Finish".

Create Ubuntu Virtual Machine in Hyper-V

Start the machine and install Couchbase

Now that you’ve created a machine, you must start it. Right-click on the machine and select "Start" (or there’s a "Start" button in the actions menu to the right).

This starts the machine, but you can’t actually see the machine yet. You have to "Connect" to the machine to see what it’s doing. Right-click and select "Connect" (or again, there’s a "Connect" button in the actions menu to the right).

Ubuntu in Hyper-V

I won’t go through the installation process, since Ubuntu’s installation is pretty easy and self-explanatory (and well-documented).

At the end of the Ubuntu installation, installing Couchbase Server is also pretty easy and self-explanatory. Just go to the Couchbase downloads page and select the Ubuntu 14 version of Couchbase.

Download Couchbase for Ubuntu


I normally use the Windows version of Couchbase, but sometimes I need to use Ubuntu (or other Linux distros). Hyper-V on Windows is a convenient way for me to spin up virtual machines.

If you have any questions about Couchbase, please ask away in the Couchbase Forums or check out the Couchbase Developer Portal.

You can also contact me at Twitter @mgroves.

Matthew D. Groves

About the Author

Matthew D. Groves lives in Central Ohio. He works remotely, loves to code, and is a Microsoft MVP.

Latest Comments