String search

You can use string searches to fetch documents based on a matching string or substring.

This guide covers common patterns for string searches in FQL queries. The examples use Fauna’s demo data.

You can use where() with an equality comparison to run exact match searches on String fields:

Product.where(.name == "cups")
{
  data: [
    {
      id: "395298017872183369",
      coll: Product,
      ts: Time("2024-04-16T05:13:37.050Z"),
      name: "cups",
      description: "Translucent 9 Oz, 100 ct",
      price: 6.98,
      quantity: 90,
      store: Store("395298017869037641"),
      backorderLimit: 5,
      backordered: false
    }
  ]
}

Equality comparisons are case-sensitive. Use toLowerCase() to make the search case-insensitive:

Product.where(.name.toLowerCase() == "CuPs".toLowerCase())

Calling where() directly on a collection requires a scan of the entire collection. It isn’t performant for large collections.

Instead, use an index with a term to run an exact match search:

Product.byName("cups")

name is the only term for the byName index. The search is case-sensitive.

Use startsWith() to match strings that begin with a specific substring. startsWith() is case-sensitive.

Customer.where(.telephone.startsWith("719-"))
{
  data: [
    {
      id: "395298017892106313",
      coll: Customer,
      ts: Time("2024-04-16T05:13:37.050Z"),
      firstName: "Bob",
      lastName: "Brown",
      address: {
        street: "72 Waxwing Terrace",
        city: "Washington",
        state: "DC",
        zipCode: "20002"
      },
      telephone: "719-872-8799",
      creditCard: {
        network: "Visa",
        number: "4916112310613672"
      }
    }
  ]
}

Use endsWith() to match strings that end with a specific substring. endsWith() is case-sensitive.

Customer.where(.lastName.endsWith("Appleseed"))
{
  data: [
    {
      id: "395298017890009161",
      coll: Customer,
      ts: Time("2024-04-16T05:13:37.050Z"),
      firstName: "Alice",
      lastName: "Appleseed",
      address: {
        street: "87856 Mendota Court",
        city: "Washington",
        state: "DC",
        zipCode: "20220"
      },
      telephone: "208-346-0715",
      creditCard: {
        network: "Visa",
        number: "4556781272473393"
      }
    }
  ]
}

Use includes() to match strings that contain a specific substring. includes() is case-sensitive.

Product.where(.description.includes("16 oz bag"))
{
  data: [
    {
      id: "395298017881620553",
      coll: Product,
      ts: Time("2024-04-16T05:13:37.050Z"),
      name: "limes",
      description: "Organic, 16 oz bag",
      price: 3.49,
      quantity: 45,
      store: Store("395298017866940489"),
      backorderLimit: 15,
      backordered: false
    },
    {
      id: "395298017883717705",
      coll: Product,
      ts: Time("2024-04-16T05:13:37.050Z"),
      name: "limes",
      description: "Conventional, 16 oz bag",
      price: 2.99,
      quantity: 22,
      store: Store("395298017870086217"),
      backorderLimit: 15,
      backordered: false
    }
  ]
}

Use includesRegex() to check for substrings matching a regular expression:

let regex = "(?:(1)?)?[-.●]?([0-9]{3})[-.●]?([0-9]{3})[-.●]?([0-9]{4})"
Customer.where(.telephone.includesRegex(regex))
{
  data: [
    {
      id: "395298017890009161",
      coll: Customer,
      ts: Time("2024-04-16T05:13:37.050Z"),
      firstName: "Alice",
      lastName: "Appleseed",
      address: {
        street: "87856 Mendota Court",
        city: "Washington",
        state: "DC",
        zipCode: "20220"
      },
      telephone: "208-346-0715",
      creditCard: {
        network: "Visa",
        number: "4556781272473393"
      }
    },
    {
      id: "395298017892106313",
      coll: Customer,
      ts: Time("2024-04-16T05:13:37.050Z"),
      firstName: "Bob",
      lastName: "Brown",
      address: {
        street: "72 Waxwing Terrace",
        city: "Washington",
        state: "DC",
        zipCode: "20002"
      },
      telephone: "719-872-8799",
      creditCard: {
        network: "Visa",
        number: "4916112310613672"
      }
    },
    {
      id: "395298017893154889",
      coll: Customer,
      ts: Time("2024-04-16T05:13:37.050Z"),
      firstName: "Carol",
      lastName: "Clark",
      address: {
        street: "5 Troy Trail",
        city: "Washington",
        state: "DC",
        zipCode: "20220"
      },
      telephone: "907-949-4470",
      creditCard: {
        network: "Visa",
        number: "4532636730015542"
      }
    }
  ]
}

Return matching substrings

matches() is similar to includes() and includesRegex() except it returns an array of matching substrings.

You can pass matches() a substring:

let name = "Denny Johnson"
name.matches('Johnson')
[
  "Johnson"
]

matches() also accepts a regular expression:

let phone = "416-695-4364"
let regex = "(?:(1)?)?[-.●]?([0-9]{3})[-.●]?([0-9]{3})[-.●]?([0-9]{4})"

phone.matches(regex)
[
  "416-695-4364"
]

Using a Customer document from the demo data:

let customer = Customer.byName("Bob" ,"Brown").first()
let regex = "(?:(1)?)?[-.●]?([0-9]{3})[-.●]?([0-9]{3})[-.●]?([0-9]{4})"

customer?.telephone.matches(regex)
[
  "719-872-8799"
]

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!