Facets

Facets are a powerful tool for filtering and narrowing down search results on the Orama search engine.

With the Orama Faceted Search API, users can filter their search results by various criteria, such as category, price range, or other attributes, making it easier to find the information they need. Whether you’re building a website, mobile app, or any other application, the Orama Faceted Search API is the perfect solution for adding faceted search functionality to your project.

Given the following Orama schema:

import { create } from "@orama/orama";

const db = create({
  schema: {
    title: "string",
    description: "string",
    categories: {
      primary: "string",
      secondary: "string",
    },
    rating: "number",
    isFavorite: "boolean",
  },
});

Orama will be able to generate facets at search-time based on the schema. To do so, we need to specify the facets property in the search configuration:

const results = search(db, {
  term: "Movie about cars and racing",
  properties: ["description"],
  facets: {
    "categories.primary": {
      limit: 3,
      order: "DESC",
    },
    "categories.secondary": {
      limit: 2,
      order: "DESC",
    },
    rating: {
      ranges: [
        { from: 0, to: 3 },
        { from: 3, to: 7 },
        { from: 7, to: 10 },
      ],
    },
    isFavorite: {
      true: true,
      false: true,
    },
  },
});

This will generate the following result:

{
  elapsed: ...,
  count: ...,
  hits: { ... },
  facets: {
    'categories.first': {
      count: 14,
      values: {
        'Action': 4,
        'Adventure': 3,
        'Comedy': 2,
      }
    },
    'categories.second': {
      count: 14,
      values: {
        'Cars': 4,
        'Racing': 3,
      }
    },
    rating: {
      count: 3,
      values: {
        '0-3': 5,
        '3-7': 15,
        '7-10': 80,
      }
    },
    isFavorite: {
      count: 2,
      values: {
        'true': 5,
        'false': 95,
      }
    },
  }
}

As you may have noticed, the facets property is an object that contains different configurations depending on the property type specified in the schema.

If a property is specified as string in the schema, the facet will accept the following configuration:

Property	Type	Default	Description
`order`	`string`	`DESC`	Order of the values. Can be either `ASC` or `DESC`.
`limit`	`number`	`10`	Maximum number of values to return.
`offset`	`number`	`0`	Number of values to skip.

In the search result, string facets will be returned as an object with the following properties:

{
  count: 14,            // Total number of values, now limited to 3 (size)
  values: {
    'Action': 4,        // Number of documents that have this value
    'Adventure': 3,     // Number of documents that have this value
    'Comedy': 2,        // Number of documents that have this value
  }
}

If a property is specified as number in the schema, the facet will accept the following configuration:

Property	Type	Default	Description
`ranges`	`array`	`[]`	Array of ranges to consider.

Each range is an object with the following properties:

Property	Type	Description
`from`	`number`	Minimum value of the range.
`to`	`number`	Maximum value of the range.

In the search result, number facets will be returned as an object with the following properties:

{
  count: 3,      // Total number of ranges
  values: {
    '0-3': 5,    // Number of documents that have a value between 0 and 3 (inclusive)
    '3-7': 15,   // Number of documents that have a value between 3 and 7 (inclusive)
    '7-10': 80,  // Number of documents that have a value between 7 and 10 (inclusive)
  }
}

Please note that the from and to values are inclusive. Note also that the order of the ranges is guaranteed as specified in the configuration.

If a property is specified as boolean in the schema, the facet will accept the following configuration:

Property	Type	Default	Description
`true`	`boolean`	`true`	Whether to consider `true` values.
`false`	`boolean`	`true`	Whether to consider `false` values.

In the search result, boolean facets will be returned as an object with the following properties:

{
  count: 2,       // Total number of values
  values: {
    'true': 5,    // Number of documents that have a `true` value
    'false': 95,  // Number of documents that have a `false` value
  }
}

If a property is specified as enum in the schema, no configuration is required. In the search result, enum facets will be returned as an object with the following properties:

{
  count: 9,            // Total number of values
  values: {
    'Action': 4,        // Number of documents that have this value
    'Adventure': 3,     // Number of documents that have this value
    'Comedy': 2,        // Number of documents that have this value
  }
}

Orama treats each array element as a single element of the facet:

const db = create({
  schema: {
    name: "string[]",
  },
});
insert(db, {
  name: ["Albus", "Percival Wulfric Brian"],
});

const results = search(db, {
  facets: {
    name: {},
  },
});

result.facets is the following object:

{
  "count": 2,
  "values": {
    "Albus": 1,
    "Percival Wulfric Brian": 1
  }
}

Facets

String facets

Number facets

Boolean facets

Enum facets

How facets works on array fields