01 Documentation

Languages:

CRUD Tutorial

Introduction

FaunaDB allows you to store objects and query them in a relational fashion. In this tutorial, we will learn how to create blog posts, update them with additional attributes and query for specific posts.

Getting Started

To follow along you will need an admin API key. Create an admin key using the admin keys interface for your FaunaDB Cloud account, or if you are using FaunaDB Enterprise, use the configured root key for your cluster.

Create a Database

UNKNOWN EXAMPLE

Getting Access to the Database

Create an initial server key for our database by using an admin key. The server key has unrestricted access to a single database.

UNKNOWN EXAMPLE

Initial Schema

FaunaDB is an object-relational database that stores data in the form of nested objects. Each object is considered an instance of a specific class. Therefore, in order to create an instance of a post, we need to first specify a class such as “posts”.

Create a class using the create_class function with a parameters object containing the name of the class. For example:

UNKNOWN EXAMPLE

Preparing Schema for Queries

Before we create instance objects, let’s pave the way to access them by creating an index using the create_index function. This is strictly for the purpose of clarity in the tutorial. In real-world scenarios, indexes can be created at any time.

The customary way to access instances of a class is by specifying a criteria for one of the fields. To enable criteria based searches, we need to first create an index using the position of the field within the instance. For example, let us create an index on the post’s title:

UNKNOWN EXAMPLE

It is also possible to specify the values of the object that should be returned when querying the index. Let’s create an index for tags that may be present on a post.

UNKNOWN EXAMPLE

Working with Data

Creating a Post

Posts are created by calling the create function with the ref of the “posts” class and a params object. The post’s data is included in the params object’s “data” field.

UNKNOWN EXAMPLE

create returns the post instance just created. The ref of the instance is an automatically generated identifier that is unique to the instance within its database.

It can quickly become tedious to repeat the create function for multiple posts.

This is where FaunaDB’s query language really shines. Let’s use a map function to create several posts at once.

UNKNOWN EXAMPLE

As you can see above, using the map function, we can restructure the data as a collection and wrap the create in a Lisp-style lambda function, which then runs over each object in the collection. The anonymous lambda function specifies a variable post_title which is used as a placeholder in the parameters sent to the create function. This way, multiple instances of a class can be created using a single query.

Retrieving Posts

The easiest way to retrieve an instance is using its reference value.

UNKNOWN EXAMPLE

You can query for posts with a specific title using the match function and the index we created earlier:

UNKNOWN EXAMPLE

The match function returns a logical set of elements, which can be combined with other sets with set-operations like join, intersect, subtract, etc.

Modifying Posts

You can easily modify instances by supplying the new data along with the reference to the instance. For example, you may want to add tags to each of your blog posts.

UNKNOWN EXAMPLE

The update function updates specific fields on an instance. It preserves the old fields if they are not specified in params. In the case of objects, the old and the new values are merged. If null is specified as a value for a field, it is removed.

The replace function, on the other hand, replaces the instance data with the fields provided in params. Therefore, old fields which are not mentioned in params are removed.

UNKNOWN EXAMPLE

Note that the title has been updated, but the tags has been deleted.

Deleting a Post

Lastly, a post can be removed using the delete function:

UNKNOWN EXAMPLE

UNKNOWN EXAMPLE

Iterating over Posts

Working with bulk data will require pagination of some sort. FaunaDB supports pagination in its query language and allows you to iterate over objects one page at a time. To understand pagination better, let’s update the post objects with some tags and use the index we created earlier, posts_by_tags_with_title to query for them.

UNKNOWN EXAMPLE

The do function takes a sequence of function calls, evaluates them one after the other and returns the response from the last one.

Now, we can use the index posts_by_tags_with_title to fetch posts that match a given tag.

UNKNOWN EXAMPLE

The paginate function returns the first page of qualifying entries from the index. The size of the page is determined by the size parameter. You can move forward or backwards page by page using the after or before value as a cursor.

UNKNOWN EXAMPLE

Since a page is also a collection in FaunaDB, collection functions can be used to process the elements further. Suppose, we wanted only the title of posts tagged with travel.

UNKNOWN EXAMPLE

The casefold function converts the given string to lowercase. The map function iterates this over the entire page of entries and returns only the titles from the pages.

Further Reading

This tutorial dealt with the simple case of creating a blog and associating some posts with it. In the next tutorial, we’ll cover social graphing.