Fauna at-a-glance

This introductory tutorial gives you a quick, at-a-glance overview of how to populate a database and manipulate its contents using built-in FQL CRUD operations. As a new Fauna user, this is foundational to gaining the insight needed before advancing to more targeted features in the tutorials that follow.

The first step is to create a database. Start by getting a Fauna account and creating a database, as described in the Dashboard quick start. Follow the quick start through step two to create the database, giving it a name you prefer. This and the following tutorials provide the data to run the examples.

Remember to enable type checking in the Dashboard or through the driver if you are using a driver to run the examples.

Now that you are set up,

Populate your database with coffee grower data.
Work through the CRUD operation exercises to add, change and delete data.

Populate the database

Create a Collection to hold the documents with your coffee grower data. A Collection is similar to a table in a relational database.

Use the Collection.create() method, which takes a name parameter that uniquely identifies the collection:
Collection.create( {name: "CoffeeBean"} )
{ name: "CoffeeBean", coll: Collection, ts: Time("2023-05-30T22:16:26.970Z"), indexes: {}, constraints: [] }
The response from Fauna includes the collection name and metadata about the collection. The indexes and constraints fields are covered in later tutorials.

This cookbook uses the CoffeeBean collection and sample data throughout.

To list all the collections in the database, use the Collection.all() method:

Collection.all()

{
  data: [
    {
      name: "Books",
      coll: Collection,
      ts: Time("2023-05-30T19:16:52.490Z"),
      indexes: {},
      constraints: []
    },
    {
      name: "CoffeeBean",
      coll: Collection,
      ts: Time("2023-05-30T22:16:26.970Z"),
      indexes: {},
      constraints: []
    }
  ]
}

You now have a CoffeeBean collection, and a Books collection that already exists in the example database. Your database might have other collections or no other collections if you’re starting with a new database.

You can list information about your collection by calling the Collection.byName() method with the name of the Collection:

Collection.byName("CoffeeBean")

{
  name: "CoffeeBean",
  coll: Collection,
  ts: Time("2023-05-30T22:16:26.970Z"),
  indexes: {},
  constraints: []
}

Now, populate your CoffeeBean collection by using the create() method to add a document. Copy and paste the provided coffee grower data to your Dashboard query:

CoffeeBean.create({
    "Species": "Arabica",
    "Owner": "metad plc",
    "Country_of_Origin": "Ethiopia",
    "Harvest_Year": 2014,
    "Quality_Parameters": {
        "Aroma": 8.67,
        "Flavor": 8.83,
        "Balance": 8.42
        },
    "Altitude": {
      "unit_of_measurement": "m",
      "mean": 2075
    }
})

Use the collection instance all() method to list the documents in your CoffeeBean collection:

CoffeeBean.all()

{
  data: [
    {
      id: "366190504817197124",
      coll: CoffeeBean,
      ts: Time("2023-05-30T22:22:09.360Z"),
      Species: "Arabica",
      Owner: "metad plc",
      Country_of_Origin: "Ethiopia",
      Harvest_Year: 2014,
      Quality_Parameters: {
        Aroma: 8.67,
        Flavor: 8.83,
        Balance: 8.42
      },
      Altitude: {
        unit_of_measurement: "m",
        mean: 2075
      }
    }
  ]
}

You can see that CoffeeBean includes your first document.

Query sets and documents

Typically, you’re working with Sets of Documents. This exercise shows you how to select and update the document you want by using the Set methods.

Start by adding a second document to your CoffeeBean collection.

Create the document using the provided coffee grower data:

CoffeeBean.create({
    "Species": "Arabica",
    "Owner": "grounds for health admin",
    "Country_of_Origin": "Guatemala",
    "Harvest_Year": "",
    "Quality_Parameters": {
      "Aroma": 8.42,
      "Flavor": 8.5,
      "Balance": 8.42
    },
    "Altitude": {
      "unit_of_measurement": "m",
      "mean": 1700
    }
})

This time when you call the all() method, you should see a Set of documents in your CoffeeBean collection:

CoffeeBean.all()

{
  data: [
    {
      id: "366190504817197124",
      coll: CoffeeBean,
      ts: Time("2023-05-30T22:22:09.360Z"),
      Species: "Arabica",
      Owner: "metad plc",
      Country_of_Origin: "Ethiopia",
      Harvest_Year: 2014,
      Quality_Parameters: {
        Aroma: 8.67,
        Flavor: 8.83,
        Balance: 8.42
      },
      Altitude: {
        unit_of_measurement: "m",
        mean: 2075
      }
    },
    {
      id: "366190711733747780",
      coll: CoffeeBean,
      ts: Time("2023-05-30T22:25:26.690Z"),
      Species: "Arabica",
      Owner: "grounds for health admin",
      Country_of_Origin: "Guatemala",
      Harvest_Year: "",
      Quality_Parameters: {
        Aroma: 8.42,
        Flavor: 8.5,
        Balance: 8.42
      },
      Altitude: {
        unit_of_measurement: "m",
        mean: 1700
      }
    }
  ]
}

Given a Set, use built-in Set methods to refine the query and get the exact document you want to view or change. For example, use the take() method to get the first document only:

CoffeeBean.all().take(1)

{
  data: [
    {
      id: "366190504817197124",
      coll: CoffeeBean,
      ts: Time("2023-05-30T22:22:09.360Z"),
      Species: "Arabica",
      Owner: "metad plc",
      Country_of_Origin: "Ethiopia",
      Harvest_Year: 2014,
      Quality_Parameters: {
        Aroma: 8.67,
        Flavor: 8.83,
        Balance: 8.42
      },
      Altitude: {
        unit_of_measurement: "m",
        mean: 2075
      }
    }
  ]
}

The take() method with a parameter of 1 returns one, the first member of the set.

Use the where() method to get a document that has a matching data field value. This query introduces FQL dot notation and method chaining, which you can learn more about in the Field accessors and method chaining language reference.

CoffeeBean.all().where(.Country_of_Origin == "Guatemala")

{
  data: [
    {
      id: "366190711733747780",
      coll: CoffeeBean,
      ts: Time("2023-05-30T22:57:36.720Z"),
      Species: "Arabica",
      Owner: "Healthy Grounds",
      Country_of_Origin: "Guatemala",
      Harvest_Year: "",
      Quality_Parameters: {
        Aroma: 8.42,
        Flavor: 8.5,
        Balance: 8.42
      },
      Altitude: {
        unit_of_measurement: "m",
        mean: 1700
      }
    }
  ]
}

Fauna returns the second document of the set.

By default, a query returns all document fields, but you can also get only those fields you want from the documents you select.

Get the Species and Country_of_Origin fields from your two CoffeeBean documents:

CoffeeBean.all().take(2) {
  Species,
  Country_of_Origin
}

{
  data: [
    {
      Species: "Arabica",
      Country_of_Origin: "Ethiopia"
    },
    {
      Species: "Arabica",
      Country_of_Origin: "Guatemala"
    }
  ]
}

The next exercise shows you how to change fields in a document.

Update a document

Documents have IDs that you can use as an alternative to the Set selection methods to reference the document you want. For simplicity, this exercise gets a document directly by referencing its id field.

The id of the first document in the collection for this example dataset is 366190504817197124. You should have a different ID because every document has a unique ID. Use ID of the document in your dataset to update the Owner name.

Use the Document update() method, passing your ID to select the document, then passing an object with the field name and new value:
CoffeeBean.byId("366190711733747780")!.update( { Owner: "Healthy Grounds, Inc." } )
{ id: "366190711733747780", coll: CoffeeBean, ts: Time("2023-05-30T22:42:02.110Z"), Species: "Arabica", Owner: "Healthy Grounds, Inc.", Country_of_Origin: "Guatemala", Harvest_Year: "", Quality_Parameters: { Aroma: 8.42, Flavor: 8.5, Balance: 8.42 }, Altitude: { unit_of_measurement: "m", mean: 1700 } }
All other fields remain unchanged.

See non-null assertion postfix to learn more about the ! operator, which is needed when static type checking is enabled.

In addition to changing a field, you can use the same update()method to add a field. Add an Acreage field with a value of 10,000 acres to the first document in the collection. You might want to view the document before adding the field by calling CoffeeBean.all().first().

Add the new field:

CoffeeBean.all().first()!.update({ Acreage: 10000 })

{
  id: "359216991466160161",
  coll: CoffeeBean,
  ts: Time("2023-03-23T16:22:02.780Z"),
  Species: "Arabica",
  Owner: "met agricultural development plc",
  Country_of_Origin: "Ethiopia",
  Harvest_Year: 2015,
  Grading_Date: "April 4th, 2015",
  Expiration: Date("2023-03-23"),
  Quality_Parameters: {
    Aroma: 8.67,
    Flavor: 8.83,
    Aftertaste: 8.67,
    Acidity: 8.75,
    Body: 8.5,
    Balance: 8.42,
    Uniformity: 10,
    Sweetness: 10,
  },
  Altitude: {
    unit_of_measurement: "m",
    low: 1950,
    high: 2200,
    mean: 2075,
  },
  Acreage: 10000,
}

To delete the field, run the same query and set the value of the field you want to delete to null:
CoffeeBean.all().first()!.update({ Acreage: null })

Replace a document

You can replace the full contents of a document using the replace() method. This replaces all fields except the id, coll, and ts metadata fields. Attempting to replace a metadata field generates an error.

Replace all fields in the first document of your CoffeeBean collection except the Owner and Country_of_Origin fields:

CoffeeBean.all().first()!.replace(
  {
    Owner: "met agricultural development plc",
    Country_of_Origin: "Ethiopia",
  })

{
  id: "366190504817197124",
  coll: CoffeeBean,
  ts: Time("2023-06-01T14:44:15.075Z"),
  Owner: "met agricultural development plc",
  Country_of_Origin: "Ethiopia"
}

Delete a document

To delete the full document and remove it from the collection, call the delete() method on the document instance.

For this exercise, use the id of one of your existing documents or create a temporary document and use the id of that document:
CoffeeBean.byId("366344087398252609")!.delete()
CoffeeBean.byId("366344087398252609") /* not found */
Call the all() method to verify that the document is removed from the collection:
CoffeeBean.all()

Delete a collection

This exercise completes the circle by showing you how to delete a collection.

You can delete a collection, its indexes, and its full set of documents by calling the delete() method on the Collection document definition.

This exercise creates a temporary collection, adds a document, and deletes the collection, which deletes all documents in the collection:

First, view the Collections that currently exist in the system:
Collection.all()
{ data: [ { name: "Books", coll: Collection, ts: Time("2023-05-30T19:16:52.490Z"), indexes: {}, constraints: [] }, { name: "CoffeeBean", coll: Collection, ts: Time("2023-05-30T22:16:26.970Z"), indexes: {}, constraints: [] } ] }
This exercise deletes the Books collection. You might have another collection that can be deleted, or you might want to create a temporary collection that can be used for this exercise. The CoffeeBean collection shouldn’t be deleted because it is convenient to use for the remaining tutorials, although you can recreate it if needed by running the Populate the database exercise again.
A Collection has an associated Collection document definition property.

View the Books definition document:
Books.definition
{ name: "Books", coll: Collection, ts: Time("2023-05-30T19:16:52.490Z"), indexes: {}, constraints: [] }
A Collection Document definition includes the name of the Collection, Collection metadata, and indexes and constraints associated with the Collection.
Delete the collection by calling the delete() method on the definition document:
Books.definition.delete()
Collection.byName("Books") /* not found */
To confirm the deletion, list the current collections in the system:
Collection.all()

Next steps

Now that you have an overview of Fauna and FQL, and have verified that your system is set up to run the remaining tutorials, continue in sequence with each tutorial or jump to the tutorial that you’re most interested in.

The API reference section can answer most of the detailed questions you might have about the API as you work through each tutorial.

Is this article helpful?

Tell Fauna how the article can be improved:
Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!

Fauna at-a-glance

Populate the database

Query sets and documents

Update a document

Replace a document

Delete a document

Delete a collection

Next steps

Keyboard shortcuts

While reading

While searching

URL fragments