Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

Bulk writes

This guide covers common patterns for bulk writes in FQL. You use bulk writes to create, update, or delete multiple collection documents in a single query.

Create multiple documents

Use the array.forEach() and collection.create() to create a collection document for each element of an object Array:

// Create an Array of objects that contain document data.
let customers = [
  {
    "name": "Ruby Von Rails",
    "email": "ruby@example.com",
    "address": {
      "street": "87856 Mendota Court",
      "city": "Washington",
      "state": "DC",
      "postalCode": "20220",
      "country": "US"
    }
  },
  {
    "name": "Scott Chegg",
    "email": "chegg@example.com",
    "address": {
      "street": "87856 Mendota Court",
      "city": "Washington",
      "state": "DC",
      "postalCode": "20220",
      "country": "US"
    }
  },
  {
    "name": "Hilary Ouse",
    "email": "ouse@example.com",
    "address": {
      "street": "87856 Mendota Court",
      "city": "Washington",
      "state": "DC",
      "postalCode": "20220",
      "country": "US"
    }
  }
]

// Use `forEach()` to create a `Customer` collection document for each
// element of the previous Array.
customers.forEach(doc => Customer.create({ doc }))
// `forEach()` returns `null`.

Reference: array.forEach(), collection.create()

Edit multiple documents

Use set.forEach() and document.update() to iteratively update each document in a Set:

// Get a Set of `Customer` collection documents with an
// `address` in the `state` of `DC`.
let customers = Customer.where( .address?.state == "DC" )

// Use `forEach()` to update each document in the previous Set.
customers.forEach(doc => doc.update({
  address: {
    street: doc?.address?.street,
    city: doc?.address?.city,
    state: "District of Columbia",
    postalCode: doc?.address?.postalCode,
    country: doc?.address?.country,
  }
})) // `forEach()` returns `null`.

Reference: set.forEach(), document.update()

Upsert multiple documents

Use an if... else expression to upsert documents. An upsert conditionally:

Creates a document if a document with the specified key doesn’t exist.
Updates an existing document if a document with the key already exists.

The following query uses an if... else expression with array.forEach(), collection.create(), and document.update().

// Create an Array of customer data to upsert.
let customersToUpsert = [
  {
    "name": "Ruby Von Rails",
    "email": "ruby@example.com",
    "address": {
      "street": "123 Coding Lane",
      "city": "Programmington",
      "state": "CA",
      "postalCode": "90210",
      "country": "US"
    }
  },
  {
    "name": "Scott Chegg",
    "email": "chegg@example.com",
    "address": {
      "street": "456 Database Drive",
      "city": "Queryville",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  {
    "name": "Hilary Ouse",
    "email": "ouse@example.com",
    "address": {
      "street": "789 Algorithm Avenue",
      "city": "Looptown",
      "state": "TX",
      "postalCode": "75001",
      "country": "US"
    }
  }
]

// Define a function to upsert each customer.
let upsertCustomer = (customerData) => {
  // Get each existing customer's by their email address.
  // The `Customer` collection contains a unique constraint
  // that enforces unique `email` field values.
  let existingCustomer = Customer.byEmail(customerData.email).first()

  if (existingCustomer == null) {
    // Create a new customer if not found.
    Customer.create(customerData)
  } else {
    // If found, update the existing customer.
    existingCustomer!.update(customerData)
  }
}

// Use `forEach()` to update each document in the previous Set.
customersToUpsert.forEach(customer => upsertCustomer(customer))
// `forEach()` returns `null`.

Reference: set.forEach(), collection.create(), document.update()

Delete multiple documents

Use set.forEach() and document.delete() to iteratively delete documents in a Set:

// Get a Set of `Customer` collection documents with an
// `address` in the `state` of `DC`.
let customers = Customer.where( .address?.state == "DC" )

// Use `forEach()` to delete each document in the previous Set.
customers.forEach(doc => doc.delete())
// `forEach()` returns `null`.

Reference: set.forEach(), document.delete()

Paginate bulk writes

Queries are subject to size limits.

If you’re performing bulk writes on a large dataset, you can use set.pageSize() and set.paginate() to perform the write over several queries instead of one.

// Get a Set of `Customer` collection documents with an
// `address` in the `state` of `DC`. Use `pageSize()`
// and`paginate()` to paginate results and
// limit each page to two documents.
let page = Customer.where( .address?.state == "DC" )
                          .pageSize(2).paginate()

// `paginate()` returns an object. The object's `data` property
// contains an Array of `Customer` documents.
let data = page.data

// Use `forEach()` to update each `Customer` document in the
// `data` Array.
data.forEach(doc => doc.update({
  address: {
    street: doc?.address?.street,
    city: doc?.address?.city,
    state: "District of Columbia",
    postalCode: doc?.address?.postalCode,
    country: doc?.address?.country,
  }
}))

// Project the `after` cursor returned by `paginate()`.
// You can use the cursor to iterate through the remaining
// pages.
page {
  after
}

The query returns an after cursor:

{
  after: "hdWDxoq..."
}

Subsequent queries use the cursor and Set.paginate() to iterate through the remaining pages:

// Uses `Set.paginate()` to iterate through pages.
let page = Set.paginate("hdWDxoq...")

let data = page.data

data.forEach(doc => doc.update({
  address: {
    street: doc?.address?.street,
    city: doc?.address?.city,
    state: "District of Columbia",
    postalCode: doc?.address?.postalCode,
    country: doc?.address?.country,
  }
}))

page {
  after
}

See Pagination

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!