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.

Import documents from a CSV or JSON

You can use the Fauna CLI's fauna import command to import collection documents from a CSV or JSON file:

fauna import --path=./customers.json --collection=Customer

Reference: fauna import

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!