Preflight Search

Preflight search is an Orama feature that allows you to run a preliminary search query that will return just the number of results that match your query. This is useful for determining if a search query will return a large number of results, which can be useful for determining if you should run a full search query and facets (if needed).

Usage

To run a preflight search, you can use the preflight: boolean property when using the search function.

Let’s see it in action:

import { create, insert, search } from "@orama/orama";

const db = await create({
  schema: {
    title: "string",
  },
});

await insert(db, { title: "Red headphones" });
await insert(db, { title: "Green headphones" });
await insert(db, { title: "Blue headphones" });
await insert(db, { title: "Yellow headphones" });

const results = await search(db, {
  term: "headphones",
  preflight: true,
});

console.log(results);

// {
//   elapsed: {
//     raw: 181208,
//     formatted: '181μs'
//   }
//   hits: []
//   count: 4
// }

The results object will return a standard Orama response, but the hits property will be an empty array.

Orama is extremely fast at searching, and loses a large portion of the elapsed time retrieving documents and assigning them to the final results.hits array.

By using a preflight request, you will be able to retrieve facets and a total number of results in a very fast manner, and then run a full search query if needed.

How is that useful?

Preflight requests are particularly useful in certain situations, like when spawned right before a query with a certain threshold.

For example, let’s say you have a large database of 50,000 products. If a user searches for a very rare product, you may end up with just a few results if the threshold is set to 0 (exact match).

By running a preflight search, you will be able to programmatically set a different threshold based on the number of results returned by the preflight search.

Scenarios

• The preflight search returns 3 results. You can set the threshold to 0.5, returning the 3 results + 50% of the fuzzy-matched results.
• The preflight search returns 10 results. You can set the threshold to 0.2, returning the 10 results + 20% of the fuzzy-matched results.
• The preflight search returns 100 results. You can set the threshold to 0, returning only the 100 exact-matched results.

Read the threshold documentation for more information on how the threshold parameter affects search results.