Home / IOS Development / Introduction to FaunaDB and FQL – agency for digital product development

Introduction to FaunaDB and FQL – agency for digital product development


To begin with, FaunaDB is a general database that combines relationships with document flexibility and has core features inspired by the clock-free, strictly serializable transaction protocol for multi-region environments, called Calvin. In other words, it is “a serverless, globally distributed, cloud database as a service.” A FaunaDB database contains collections of documents. (Throughout the post I will refer to a number of terms. Here is a handy FaunaDB Cheat Sheet for reference. It may be worth keeping this open in a separate tab when reading through the post). Let us now dive into the details.


To get started with FaunaDB, sign up for a new account. Then you will

  • create your first database,
  • create a collection in your database,
  • add a document to your collection, and
  • index the documents in the collection.

Sign up

Sign up for a free FaunaDB account. From September 2020, FaunaDB offers a generous free level to get started with.

Form for registration for fauna

Create a database

Visit Cloud Dashboard. Click to create a new database. Name the database www. Do not check the box “Pre-fillate with demo data”; you will add your own data shortly.

create a new database in faunaQuery the database

Queries to FaunaDB are written in Fauna Query Language (FQL), a functional query language. Fauna offers client drivers in different languages, so you can interact with FaunaDB from your code base. But for this blog post, type all the FQL into your browser using FaunaDB’s Web Shell using the JavaScript driver.

Open Web Shell

Navigate to the Web Shell for the new database using the page navigation by clicking >_ Shell link.

Fauna web shellUse Web Shell to execute FQL by typing each search in the black input console at the bottom of Web Shell and clicking Run Query.

Create a collection

ONE Collection resembles a table in a relational database. It has a unique name, as “users”, and holds Documents, as the details of each user.

Make your first Collection cold users from Web Shell using the CreateCollection () function with the following FQL query:

CreateCollection({ name: "users" })
create collection in Fauna web shell

This answer object contains four fields:

  • ONE ref field with the value of Collection("users") used to create relationships with the collection,
  • one ts field with an integer value representing the time stamp in UTC with nanosecond precision,
  • one history_days field by default 30 days which is the number of days to keep the document history, and
  • one name field with the value "users" which you stated as the logical name of the collection.
  ref: Collection("users"),
  ts: 159846586441000,
  history_days: 30,
  name: "users"

Create a document

ONE Document is like a row, and like the abstraction that is “the row”, a document can be used to model almost anything. Even the newly created one www database and users collection is Documents.

Add one user document to your "users" collection by passing The collection name and The document param_object with credentials and data fields to the Create () function:

Create("users", {
  credentials: { password: "F4un4I$Fun" },
  data: { name: "Richard", email: "rflosi@bignerdranch.com" }

The credentials the object includes one password which is stored as a BCrypt hash in FaunaDB. Providing credentials with a password is a way to allow users to authenticate using the Login () function.

The data object is a formless JSON object for your document with name and email Enger. You can specify which fields you like here.

Fauna web shell create document This answer object has three fields:

  • ONE ref fields whose value includes Collection("users") ref and a unique document ID,
  • one ts field with an integer timestamp value, and
  • one data fields that contain your document data that includes the user name and email address field.
  ref: Ref(Collection("users"), "274944144667836946"),
  ts: 1598466019230000,
  data: {
    name: "Richard",
    email: "rflosi@bignerdranch.com"

NOTE: credentials you stated will NOT be returned.

Create an index

Indexes allow the organization and retrieval of documents with attributes other than references. When you create an index, you specify the source, which is one or more collections of documents. An Index allows you to uniquely define constraints and simplifies effective data lookup.

Create a unique Index of our users of email address using the CreateIndex () function:

  name: "users_by_email",
  source: Collection("users"),
  terms: [{ field: [ "data", "email" ] }],
  unique: true,
  permissions: {},
fauna web shell create index

This answer object has nine fields:

  • ONE ref field whose value is Index("users_by_email") which you use to query for email address,
  • one ts field with an integer timestamp value,
  • one active field with the value true indicating whether the index has completed the building,
  • one serialized field with the value of true indicating that writing is serial with simultaneous reading and writing,
  • one name field with the value "users_by_email", which you entered as the logical name of your index,
  • one source field with the value of Collection("users") which defines which collection (s) to index
  • one terms field whose value is a matrix with one object with the key on field. field is an array that defines the path of the data you want to index. In this case, you index email field below data object, hence the path ["data", "email"],
  • one unique field with the value true which ensures that the indexed terms will be unique to the collection, and
  • one partitions field with the value of 1 which represents the number of sets defined by terms used to improve index performance.
  ref: Index("users_by_email"),
  ts: 1598466147239300,
  active: true,
  serialized: true,
  name: "users_by_email",
  source: Collection("users"),
  terms: [
      field: ["data", "email"]
  unique: true,
  partitions: 1

Get user via email address

Notice a user of email address using our users_by_email Index with the Match () function, and use the Paginate () function to get the first page of results from the matched set. Use the following questions to retrieve the first page user references:

  Match(Index("users_by_email"),  "rflosi@bignerdranch.com")

fauna web shell match indexThis reply item has one field:

  • ONE data field with a series of references to the corresponding documents.
  data: [Ref(Collection("users"), "274944144667836946")]

A Ref () is similar to a foreign key in a relational database and is how relationships are represented in FaunaDB. When you call the Get () function on our Ref () object, FaunaDB gets back the referenced Document. Calling the Get () function on a Match () result will retrieve the first one Document from that result set. Use the following questions to retrieve user document:

  Match(Index("users_by_email"), "rflosi@bignerdranch.com")

fauna web shell gets battleThis answer object has three fields:

  • ONE ref fields whose value is a reference to the user document,
  • one ts field with an integer timestamp value, and
  • one data field whose value is an object that contains the user name and email address.
  ref: Ref(Collection("users"), "274944144667836946"),
  ts: 1598466019230000,
  data: {
    name: "Richard",
    email: "rflosi@bignerdranch.com"


In this post you created a new database called www, added a collection called users which acts as a table, add a document to the collection that acts as a row in the table and thus creates an instance of a user, and created an index of users by their unique email addresses.

Next step

FaunaDB has much more to offer. Here are some more highlights for further exploration.

Custom features

In addition to the built-in FQL functions, you can create your own custom functions to extend FQL or encapsulate the logic.

Built-in user authentication and authorization

As mentioned, the password defined in credentials will allow you to authenticate using Login() function.

You may have noticed the use of permissions: {} when you created your index. permissions indicates who is allowed to read the index. By default, anyone can read the index. Setting permissions to an empty object removes all permissions; an omnipotent server key is then required to access the index. Configuration of permissions in this way is, however, discontinued in favor of user-defined roles and attribute-based access control (ABAC).

Comparison with other databases

If you are familiar with SQL databases, you may want to explore the Fauna Query Language for SQL users to better understand how SQL queries are translated into FQL queries.

If you are familiar with NoSQL databases, you may want to compare MongoDB and FaunaDB or DynamoDB and FaunaDB.

GraphQL support

As an alternative to creating collections and indexes with FQL, you can import a GraphQL schema that is translated into corresponding FaunaDB collections and indexes. Once a GraphQL schema is defined, you can query your GraphQL database. FaunaDB’s GraphQL endpoint will translate your GraphQL queries into FQL and provide results in JSON.


Source link