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.

Get unique field values

This guide covers how to best get unique values for a field from a Set of documents.

As an example, the guide shows you how to get unique name field values from Product collection documents. An example of a Product document:

{
  id: "111",
  coll: Product,
  ts: Time("2099-07-30T16:03:51.840Z"),
  name: "cups",
  description: "Translucent 9 Oz, 100 ct",
  price: 698,
  stock: 100,
  category: Category("123")
}

Define an index that covers the field

Add the field as an index value in an index definition:

collection Product {
  ...
  // Defines the `sortedByPriceLowToHigh()` index.
  // The index includes the `name` field as an index value.
  // The index can include `terms` and other `values`.
  index sortedByPriceLowToHigh {
    values [.price, .name, .description, .stock]
  }
}

Using an index improves performance and reduces costs by avoiding the need to read each document individually.

Extract unique values in a small Set

If your Set contains fewer than 16,000 documents, you can use an FQL query to get unique values for the field. In the query:

  • Use set.map() to iterate through each Product collection document.

  • Use set.toArray() to convert field values to an Array.

  • Call array.distinct() to return a deduplicated Array containing only unique elements.

  • Optionally, call array.order() to sort the deduplicated Array.

// Uses `map()` to return a Set of `name` field values
// from `Product` collection documents.
Product.sortedByPriceLowToHigh().map(doc => doc.name)
  // `toArray()` converts the Set to an Array.
  .toArray()
  // `distinct()` returns a deduplicated Array.
  .distinct()
  // (Optional) `order()` sorts the deduplicated Array.
  .order()
[
  "avocados",
  "cilantro",
  "cups",
  "donkey pinata",
  "limes",
  "organic limes",
  "pizza",
  "single lime",
  "taco pinata"
]

Extract unique values in a large Set

If your Set contains 16,000 or more documents, the previous query would require pagination. array.distinct() would only be able to extract unique elements from each page of results.

Instead, it’s more efficient to retrieve all field values and process them on the client side. For example, using Fauna’s JavaScript client:

// Uses `map()` and `pageSize() to get the `name` field values
// of all `Product` collection documents in batches of 500.
const query = fql`Product.sortedByPriceLowToHigh()
  .map(doc => doc.name)
  .pageSize(500)`

const iter = client.paginate(query)

// In JavaScript, a `Set` object only stores unique values.
const names = new Set()
for await (const name of iter.flatten()) {
  names.add(name)
}

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!