Sets

Reference: Set

A set is an FQL data type that contains an iterable, unbounded group of values. You typically fetch documents from a collection as a set.

Get a set of collection documents

You can fetch a set of documents from a collection by calling a collection instance method that returns a set. For example, you can call an index to get a filtered list of documents:

// Uses the `Product` collection's `sortedByPriceLowToHigh()`
// index to get `Product` documents with a
// `price` greater than or equal to `199` ($1.99):
Product.sortedByPriceLowToHigh({ from: 1_99 })
{
  // Returns matching `Product` documents as a set:
  data: [
    {
      id: "<DOCUMENT_ID>",
      coll: Product,
      ts: Time("2099-08-20T18:18:47.100Z"),
      name: "limes",
      description: "Conventional, 16 oz bag",
      price: 299, // $2.99 in cents
      ...
    },
    ...
  ]
}

Transform sets with set instance methods

You can use set instance methods to transform a fetched set. For example, you can:

// Uses the`Product` collection's `sortedByPriceLowToHigh()`
// index and `where()` to get `Product` collection documents with:
// - A `price` greater than or equal to `1_99` ($1.99)
// - A `stock` greater than `50`
Product.sortedByPriceLowToHigh({ from: 1_99 }).where(.stock > 50)
Reference: Set instance methods

Pagination

Fauna automatically paginates result sets with 16 or more elements. When a query returns paginated results, Fauna materializes a subset of the set with an after pagination cursor:

// Uses the `Product` collection's `sortedByPriceLowToHigh()` index to
// return all `Product` documents.
// The collection contains more than 16 documents.
Product.sortedByPriceLowToHigh()
{
  // The result set contains 16 elements.
  data: [
    {
      id: "404851181399048225",
      coll: Product,
      ts: Time("2099-07-30T15:57:03.730Z"),
      name: "single lime",
      description: "Conventional, 1 ct",
      ...
    },
    {
      id: "404851181404291105",
      coll: Product,
      ts: Time("2099-07-30T15:57:03.730Z"),
      name: "cilantro",
      description: "Organic, 1 bunch",
      ...
    },
    ...
  ],
 // Use the `after` cursor to get the next page of results.
  after: "hdW..."
}

To get the next page of results, pass the after cursor to Set.paginate(). To change the default page size, use set.pageSize().

See Pagination

Sets vs. arrays

While both are iterable, sets differ from FQL arrays as follows:

Difference Set Array

Purpose

Typically represents a dynamic and potentially large set of documents from a collection.

Represents a fixed sequence of known values. Limited to 16,000 elements.

Order

Unordered. You order sets using indexes and set instance methods. Elements don’t have index numbers.

Ordered. Each element has a specific index number.

Pagination

Result sets are paginated. See Pagination.

Arrays are not paginated.

Persistable

Not persistable. A set is dynamic and can’t reliably stored, retrieved, and updated in a Fauna database.

An array of other persistable values is persistable.

Supported methods

Supports set instance methods.

Supports array instance method.

Loading strategy

Some set instance methods lazily load the set. Other set instance methods eagerly load the set. Lazy-loading methods only return a result set when the query forces the set to be materialized.

All array instance methods eagerly load and materialize the entire array.

Interoperability between sets and arrays

For interoperability, most set instance methods have an equivalent array instance method (and the reverse).

You can use the set.toArray() and array.toSet() methods to cast between the set and array data types.

Use a set as a field value

Sets are not persistable. You can’t store a set as a field value or create a field definition that accepts a set.

Instead, use a computed field to define a read-only function that dynamically fetches the set at query time:

collection Customer {
...
// Computed field definition for the `orders` field.
// `orders` contains a set of `Order` documents.
// The value is computed using the `Order` collection's
// `byCustomer()` index to get the customer's orders.
compute orders: Set<Order> = ( customer => Order.byCustomer(customer))
...
}

If not projected, Fauna returns a field value containing a set as an after cursor that references the set:

// Get a `Customer` document.
Customer.byEmail("alice.appleseed@example.com").first()
{
  id: "<CUSTOMER_DOCUMENT_ID>",
  coll: Customer,
  ts: Time("2099-08-20T21:09:41.720Z"),
  cart: Order("<ORDER_DOCUMENT_ID>"),
  // `orders` contains an `after` cursor that
  // references the set of `Order` documents.
  orders: "hdW...",
  name: "Alice Appleseed",
  email: "alice.appleseed@example.com",
  ...
}

To traverse the reference, project the computed field:

// Project the `name`, `email`, and `orders` fields.
Customer.byEmail("alice.appleseed@example.com").first() {
  name,
  email,
  orders
}
{
  name: "Alice Appleseed",
  email: "alice.appleseed@example.com",
  // When projected, the `orders` field
  // contains the resolved set of `Order` documents.
  orders: {
    data: [
      {
        id: "<ORDER_DOCUMENT_ID>",
        coll: Order,
        ts: Time("2099-08-20T21:09:41.720Z"),
        items: "hdW...",
        total: 5392,
        status: "cart",
        customer: Customer("<CUSTOMER_DOCUMENT_ID>"),
        createdAt: Time("2099-08-20T21:09:41.495353Z"),
        payment: {}
      }
    ]
  }
}

Alternatively, pass the after cursor to Set.paginate():

Set.paginate("hdW...")
{
  // Returns a set of `Order` documents.
  data: [
    {
      id: "<ORDER_DOCUMENT_ID>",
      coll: Order,
      ts: Time("2099-08-20T21:09:41.720Z"),
      items: "hdW...",
      total: 5392,
      status: "cart",
      customer: Customer("<CUSTOMER_DOCUMENT_ID>"),
      createdAt: Time("2099-08-20T21:09:41.495353Z"),
      payment: {}
    },
    ...
  ]
}

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!