How to do simple writes and bulk writes in Fauna Query Language (FQL)

Write operations come in a few flavors and here we will be talking about two of them. Writing new documents and writing multiple documents in one transaction.

Write operations using FQL v10

Let’s create a new product in the Product collection using FQL's create() function.

Product.create(
  {
    name: "Twix bars", 
    quantity: 500,
    backorderLimit: 100,
    backordered: false,
    description: "Two twix bars",
    price: 2.50,
    currency: "EUR"
  }
)

When you write a document, Fauna auto-generates a unique ID for that document and adds it to the document. You can override this behavior and put your own ID in there. It's a string-encoded 64-bit integer.

{
  id: "392267523250192452",
  coll: Product,
  ts: Time("2024-03-13T18:25:12.120Z"),
  name: "Twix bars",
  quantity: 500,
  backorderLimit: 100,
  backordered: false,
  description: "Two twix bars",
  price: 2.5,
  currency: "EUR"
}

In addition, Fauna adds a timestamp of when the document was written and which collection it is in.

Bulk write operations in FQL v10

Now that you have seen a .create() operation to write a single JSON document into a Collection, let’s talk about how to do bulk writes. The easiest way is to create an array of documents and then use one of FQL’s functions to iterate through that array and write each of those documents to a database collection.

Let’s first look at how to do that in pure FQL.

Using FQL, I create three documents and a variable called myArrayOfDocs and assign it an array of those three documents.

let store1 = Store.byName("Party Supplies").first()
let doc1 = {name: "Rom", description: "A chocolate bar", store: store1}
let doc2 = {name: "Payday", description: "Peanuts and nougat", store: store1}
let doc3 = {name: "Toblerone", description: "Honey and Almond Nougat", store: store1}

let myArrayOfDocs = [ doc1, doc2, doc3 ]
myArrayOfDocs.forEach(doc=>{Product.create(doc)})

Next, we iterate through that array with the .forEach() function, and for each document in the array, we call FQL’s create() function passing in that document.

In the Fauna JavaScript driver, you could do something similar.

I create an array of documents and then use the Fauna client connection object to run a query, passing in an FQL statement.

const myArrayOfDocs = [ doc1, doc2, doc2 ]

client.query(fql`
  ${myArrayOfDocs}.forEach(x=>{
    myCollectionName.create(x)
  })
`)

One difference here is I am using the array of objects that’s a JavaScript variable, not an FQL variable. I am using it inside the FQL statement by encapsulating that variable name with like this: ${variable}. While this example is in JavaScript, you can do this with variables in your language of choice. Check our docs for examples in other languages.

A key thing to be aware of here is this entire operation generates a single transaction that is strongly consistent across all nodes in the Fauna Region Group your database is in. Either all of the operations in the transaction commit, or none of them do. If the array has 1000 documents, as we have it written here, all of the writes will be committed, or not, in one transaction, and you could hit up against Fuana’s service guardrails, but I will talk about this in another post.