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.
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 an initial
server key for our database by using an
admin key. The
server key has unrestricted access to a single database.
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:
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:
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.
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.
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
This is where FaunaDB’s query language really shines. Let’s use a
to create several posts at once.
As you can see above, using the
map function, we can restructure the data as
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.
The easiest way to retrieve an instance is using its reference value.
You can query for posts with a specific title using the
match function and the
index we created earlier:
match function returns a logical set of elements, which can be combined
with other sets with set-operations like
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.
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.
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.
Note that the
title has been updated, but the
tags has been deleted.
Lastly, a post can be removed using the
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,
to query for them.
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.
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
before value as a cursor.
page is also a collection in FaunaDB, collection functions can be
used to process the elements further. Suppose, we wanted only the
posts tagged with travel.
casefold function converts the given string to lowercase. The
function iterates this over the entire
page of entries and returns only the
titles from the pages.
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.