Facets

Your movies are searchable by title and plot. Now let visitors narrow things down — "sci-fi only", "made after 2005". That's what facets are for.

What a facet is

A facet is a field you filter or group by, rather than search inside. Genre, year, rating, "in stock" — anything with a fixed set of values a visitor might want to click to narrow their results. Facets are also what powers the little checklists down the side of a results page ("Sci-Fi (3), Action (1)"), because Search Stack can count how many results fall into each value.

Each facet has a type so filtering behaves sensibly: text like a genre is a String, a year is a Number, a release date is a Date, an in-stock flag is a Boolean.

Add genre and year

On the movies list, choose Fields then Add Facet Field. Add genre as a String, then add year as a Number.

Edit each film to fill in its genre and year, just like you did for the plot. The list now carries all four fields:

Filter a search

Every facet value comes back automatically in each search result, so a client can show "Sci-Fi · 2010" beside a film with no extra request. To restrict results, add a filter to the search. This finds sci-fi films made after 2005:

GET https://api.searchstack.dev/search/Demo/movies/1?query=&filter=genre eq 'Sci-Fi' and year gt 2005
X-API-Key: {your key}

returns just the matching films:

{
  "results": [
    { "name": "Inception",     "fields": { "genre": "Sci-Fi", "year": 2010 } },
    { "name": "Interstellar",  "fields": { "genre": "Sci-Fi", "year": 2014 } }
  ],
  "count": 2,
  "total_count": 2
}

List a facet's values

To build a filter dropdown you need to know which values exist. Ask for a facet's distinct values directly — the same read key the search endpoints use works here:

GET https://api.searchstack.dev/facet/Demo/movies/1/genre
X-API-Key: {your key}

["Sci-Fi", "Thriller", "Drama"]

The filter grammar

Filters use a small, readable expression language. Text values go in single quotes; numbers and dates don't. Combine clauses with and, or and not.

The same filter works on the suggest operation too, so your autocomplete box can respect a "Sci-Fi only" toggle as the visitor types.

Next we'll add a field for data you don't search or filter on at all — the film's poster image.