set.includes()

Learn: Sets

Test if the Set includes a provided element.

Signature

includes(element: A) => Boolean

Description

Tests if the Set includes a provided element.

Eager loading

This method uses eager loading and requires a read of each document in the calling Set. For large Sets, this may result in poor performance and high costs.

Performance hint: full_set_read

Queries that call this method on a document Set emit a performance hint, if enabled. For example, the following query:

// Use `includes()` to check whether the `Product`
// collection includes a specific document.
let limes: Any = Product.byId("777")
Product.all().includes(limes)

Emits the following hint:

performance_hint: full_set_read - Using includes() causes the full set to be read. See https://docs.fauna.com/performance_hint/full_set_read.
at *query*:4:23
  |
4 | Product.all().includes(limes)
  |                       ^^^^^^^
  |

To address the hint, use set.take() to explicitly limit the size of the calling Set to fewer than 100 documents:

// Limit the doc Set's size using `take()`
let limes: Any = Product.byId("777")
Product.all().take(20).includes(limes)

This applies even if the original, unbounded Set contains fewer than 100 documents.

Alternatively, you can rewrite the query to avoid calling the method.

Avoid filtering using includes()

In most cases, you should avoid using set.includes() to intersect results, including results from covered index calls.

set.includes() is a linear operation. The compute costs consumed by repeatedly iterating through results will typically exceed the read costs of directly reading documents.

For example, the following query is inefficient and will likely incur high compute costs:

// Each variable is a covered index call
let limes = Product.byName("limes")
let produce = Product.byCategory(Category.byName("produce").first()!)
let under5 = Product.sortedByPriceLowToHigh({ to: 500 })

// Uses `includes()` to intersect the results from
// covered index calls
limes.where(doc => produce.includes(doc))
     .where(doc => under5.includes(doc))

Instead, use a covered index call and set.where() to filter the results as outlined in Filter using where(). For example, you can rewrite the previous query as:

// Start with a covered index call.
Product.byName("limes")
  // Layer on filters using `where()`
  .where(doc => doc.category == Category.byName("produce").first()!)
  .where(doc => doc.price < 500 )

Parameters

Parameter Type Required Description

element

Generic

true

Element to check the Set for.

Return value

Type Description

Boolean

If true, the Set contains the provided element. Otherwise, false.

Examples

// `toSet()` converts an Array to a Set.
let set = [1, 2, 3].toSet()
set.includes(2)
true
\