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.

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

Product.where(.name == "cups")

Results:

{
  data: [
    {
      id: "<DOCUMENT_ID>",
      coll: Product,
      ts: Time("2099-07-30T16:03:51.840Z"),
      name: "cups",
      description: "Translucent 9 Oz, 100 ct",
      price: 698,
      stock: 100,
      category: Category("<CATEGORY_DOCUMENT_ID>")
    }
  ]
}

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

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

Calling collection.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 string.startsWith() to match strings that begin with a specific substring. string.startsWith() is case-sensitive.

Customer.where(.name.startsWith("Al"))
{
  data: [
    {
      id: "111",
      coll: Customer,
      ts: Time("2099-07-30T16:03:51.840Z"),
      cart: Order("<ORDER_DOCUMENT_ID>"),
      orders: "<ORDERS_SET_AFTER_CURSOR>",
      name: "Alice Appleseed",
      email: "alice.appleseed@example.com",
      address: {
        street: "87856 Mendota Court",
        city: "Washington",
        state: "DC",
        postalCode: "20220",
        country: "US"
      }
    }
  ]
}

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

Customer.where(.name.endsWith("Appleseed"))

Results:

{
  data: [
    {
      id: "111",
      coll: Customer,
      ts: Time("2099-07-30T16:03:51.840Z"),
      cart: Order("<ORDER_DOCUMENT_ID>"),
      orders: "<ORDERS_SET_AFTER_CURSOR>",
      name: "Alice Appleseed",
      email: "alice.appleseed@example.com",
      address: {
        street: "87856 Mendota Court",
        city: "Washington",
        state: "DC",
        postalCode: "20220",
        country: "US"
      }
    }
  ]
}

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

Product.where(.description.includes("16 oz bag"))

Results:

{
  data: [
    {
      id: "<DOCUMENT_ID>",
      coll: Product,
      ts: Time("2099-07-30T16:03:51.840Z"),
      name: "organic limes",
      description: "Organic, 16 oz bag",
      price: 349,
      stock: 50,
      category: Category("<CATEGORY_DOCUMENT_ID>")
    },
    {
      id: "<DOCUMENT_ID>",
      coll: Product,
      ts: Time("2099-07-30T16:03:51.840Z"),
      name: "limes",
      description: "Conventional, 16 oz bag",
      price: 299,
      stock: 30,
      category: Category("<CATEGORY_DOCUMENT_ID>")
    }
  ]
}

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

// Regex for 5-digit postal codes that begin with `2`.
let regex = "(2[0-9]{4})"
Customer.where(.address.postalCode.includesRegex(regex))

Results:

{
  data: [
    {
      id: "111",
      coll: Customer,
      ts: Time("2099-07-30T16:03:51.840Z"),
      cart: Order("<ORDER_DOCUMENT_ID>"),
      orders: "<ORDERS_SET_AFTER_CURSOR>",
      name: "Alice Appleseed",
      email: "alice.appleseed@example.com",
      address: {
        street: "87856 Mendota Court",
        city: "Washington",
        state: "DC",
        postalCode: "20220",
        country: "US"
      }
    },
    ...
  ]
}

Return matching substrings

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

You can pass string.matches() a substring:

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

string.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"
]

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!