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.

set.order()

Sort a Set's elements.

Signature

order(ordering: ...(A => Any) & {}) => Set<A>

Description

Creates a sorted Set by applying one or more sorting criteria to the calling Set.

You define each sorting criterion by wrapping asc() (ascending) or desc() (descending) around a field accessor or a read-only anonymous function.

The first criterion has the highest sorting priority, with priority decreasing for each subsequent criterion.

If order() is the last value in an expression, the first page of the new Set is returned. See Pagination.

The calling Set remains unchanged.

Using order() with indexes

Calling order() on an index, including the built-in all() index, requires a read of each document and historical document snapshot covered by the index.

For example:

// Calls `order` on the built-in `all()` index.
// The query requires a read of each current `Product`
// collection document and any historical document snapshots.
Product.all().order(.price) { price }
Performance hint: full_set_read

Queries that call order() on an index emit a performance hint, if enabled. For example:

performance_hint: full_set_read - Using order() causes the full set to be read. See https://docs.fauna.com/performance_hint/full_set_read.
at *query*:4:20
  |
4 | Product.all().order(.price) { price }
  |                    ^^^^^^^^
  |

If you frequently run such queries, consider adding the fields used for ordering to an index definition’s values. For example:

collection Product {
  ...
  // Adds `price` as an index value.
  index sortedByPriceLowToHigh {
    values [.price]
  }
  ...
}

When you call the index, returned documents are sorted by the index’s values. Using index values can significantly reduce the number of read ops required to sort results.

// Get `Product` documents by
// Ascending `name`, then ...
// Ascending `id` (default)
// This is equivalent to the previous query.
Product.sortedByPriceLowToHigh() { price }

Parameters

Parameter Type Required Description

ordering

Generic

One or more sorting criteria, separated by commas.

Each criterion is a field accessor or read-only anonymous function, optionally wrapped in asc() (ascending) or desc() (descending) to indicate sort order.

If neither asc() or desc() is provided, asc() is used by default.

The anonymous function is passed each Set element as an argument. For document Sets, each Set element is a Document.

Return value

Type Description

Set<Generic>

New Set with elements in requested order.

Examples

Sort fields in ascending order

// Sort `Customer` collection documents by `name`
// in ascending order (default).
Customer.all().order(.name) { name, email }
{
  data: [
    {
      name: "Alice Appleseed",
      email: "alice.appleseed@example.com"
    },
    {
      name: "Bob Brown",
      email: "bob.brown@example.com"
    },
    {
      name: "Carol Clark",
      email: "carol.clark@example.com"
    }
  ]
}

Sort fields in descending order

// Sort `Customer` collection documents by `name`
// in descending order.
Customer.all().order(desc(.name)) { name, email }
{
  data: [
    {
      name: "Carol Clark",
      email: "carol.clark@example.com"
    },
    {
      name: "Bob Brown",
      email: "bob.brown@example.com"
    },
    {
      name: "Alice Appleseed",
      email: "alice.appleseed@example.com"
    }
  ]
}

Sort fields using multiple arguments

// Sort `Customer` collection documents by:
// - Ascending `name` then...
// - Ascending `address.street`.
Customer.all().order(.name, .address.street) { name, address { street }, email }
{
  data: [
    {
      name: "Alice Appleseed",
      address: {
        street: "87856 Mendota Court"
      },
      email: "alice.appleseed@example.com"
    },
    {
      name: "Bob Brown",
      address: {
        street: "72 Waxwing Terrace"
      },
      email: "bob.brown@example.com"
    },
    {
      name: "Carol Clark",
      address: {
        street: "5 Troy Trail"
      },
      email: "carol.clark@example.com"
    }
  ]
}

Sort fields using an anonymous function

In addition to using field accessors, you can use a read-only anonymous function as a sorting criterion:

// Sort Customer collection documents by prioritizing
// those where the email contains "example.com".
Customer.all().order(asc(
  (doc) => if (doc.email.includes("example.com")) {
    // Prioritize these documents.
    // Lower numbers (`0`)` appear first when sorted
    // in ascending order.
    0
  // After that, sort the remaining documents by the
  // length of their email.
  } else {
    doc.email.length
  }
)) { name, email }
{
  data: [
    {
      name: "Alice Appleseed",
      email: "alice.appleseed@example.com"
    },
    {
      name: "Bob Brown",
      email: "bob.brown@example.com"
    },
    {
      name: "Carol Clark",
      email: "carol.clark@example.com"
    },
    {
      name: "Jane Doe",
      email: "12-fake@fauna.com"
    },
    {
      name: "John Doe",
      email: "123-fake@fauna.com"
    }
  ]
}

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!