Nothing too dramatic: the database contains a list of students and a list of courses. Each student can enrol on any number of courses, and the record of each of the student’s enrollments is stored in a separate table called enrollment, which links to the student’s record and the courses they are enrolling on.

The enrollment table highlights one of the problems with the relational database model: each table is based on a fixed schema that can only support a single data object type. You cannot store, for example, the enrollment records in the same table as the student, even though it may more natural to do so; after all, an enrollment cannot exist without a student, so why not store them together?

The document model gives you the same decomposition advantages as the relational model, but additionally, it also supports complex types which allows for a much more flexible design.

Here’s how the student record system might look as a document database:

The document is stored in JSON format, which allows for the storage of complex types such as arrays without decomposing them to a second table. JSON also allows the flexibility to change the structure of the document without having to rebuild schemas (as you would in a relational database system). A new field, let’s say to store email addresses, could be added to new documents without having to migrate existing data to a new schema. In this case, the list of enrollment records is stored with the student record. Each enrollment record holds a reference to the course it relates to.

Couchbase uses a document model which stores each database record as a JSON document. The document can contain both simple scalar types, and complex types such as nested records and arrays.

Hilary’s enrollments are stored in the same document as her student details. As well as being a more natural way to store child information with its parent, this structure allows for all of Hilary’s details (enrollments included) in one search, without the need for complex table joins to retrieve the enrollment information.

Sign up to of the Couchbase Capella cloud service and deploy a free tier cluster to properly run through the tutorials for Getting Started with Couchbase Capella.

Make a note of the database endpoint, and any user names and passwords that you set up. You will use these to access your Capella database from the Scala SDK.

The next thing to do is create the bucket where you’re going to store your documents. You will also learn other ways in which Couchbase allows you to logically partition your data.

If you think in RDBMS terms, a Couchbase Bucket is analogous to a database: it’s the data store where you’re going to store and retrieve related information about the students.

You can click on the Dashboard  Buckets link to access the Buckets page, then click on Add Bucket.

In this dialog, enter student-bucket in the Name box.

Once you have entered the bucket name, press the Add Bucket button to return to the main bucket list.

In all but the simplest cases, it’s better to provide some kind of separation between documents of different types. Couchbase has a simple hierarchy model which allows for such separation:

You’re already familiar with clusters, nodes, and buckets. Inside a bucket you can also have any number of scopes (up to a thousand), and inside a scope you can have any number of collections (again, up to a thousand).

Rather than have our student records stored in the default collection, we’re going to add two collections: one will be used to store the student records, the other will be used to store the course details.

Now looking again at the relational design of our student database:

We can see that our equivalent document-based system could do with a little decomposition:

So, inside our student-bucket we’ve set up a scope called art-school-scope. Perhaps we have a number of schools and we want to restrict access to the school based on the role of the user; using scopes is the ideal way to do it.

Within the scope we set up two collections:

Now that you understand the basics of scopes and collections, return to your administration screen so we can add them to your bucket.

Return to the Buckets screen and click the Scopes & Collections link.

Although the bucket is created with a default scope, for this example, you’re going to create your own. Click on the Add Scope link.

On the next dialog, create your art-school-scope.

Press Save to save the new scope and return to the bucket screen. The new scope should be showing in the list.

To keep things as light as possible, we’re not going to worry about building a web front end or REST service, just a few methods to read/write our documents to the database.

You will need a few things installed on your machine before you begin:

More details of the installation process are in the full installation guide. In most cases, given the above prerequisites, it’s a simple matter of the following for your favorite build tool:

Create the following directory structure on your machine:

Unresolved include directive in modules/hello-world/pages/student-record-developer-tutorial.adoc - include::partial$student-mvn-directory-structure.adoc[]

Create a new file in the directory called pom.xml in the student directory. The pom file should be populated as follows:

Unresolved include directive in modules/hello-world/pages/student-record-developer-tutorial.adoc - include::partial$student-mvn-directory-structure.adoc[]

You can test the setup is correct by opening a terminal window and changing to the student directory. Run the build script to pull in all the dependencies.

You’re now ready to write your first Couchbase application.

Earlier, you created a directory structure to hold your application. Create the file student.java in the java directory as shown below.

Unresolved include directive in modules/hello-world/pages/student-record-developer-tutorial.adoc - include::partial$student-mvn-directory-structure.adoc[]

Add the following content to the ConnectStudent.java file:

If you’re familiar with the JDBC API then connecting to a Couchbase server is not that different:

Somewhere in the output, you’ll find the line containing the name of the collection you’ve successfully retrieved:

Okay, so you’ve connected to the cluster and retrieved your collection. Unfortunately, there’s nothing in there to see at the moment, so the next thing to do is create a few records.

Good question. You may want to get hold of id field, which as you can see, isn’t returned with the document, even if we’re asking for all the fields in the call. The primary key exists as part of the document’s "meta" structure, which can be interrogated along with the rest of the document. Make the following small adjustment to the SQL++ statement and run the query again:

The META() function call will return any property contained in the document’s metadata, including its id:

You can find a full rundown of the SQL++ language here: n1ql:n1ql-language-reference/index.adoc.