New "Filtering and sorting" section

.code-samples.meilisearch.yaml

@@ -1053,7 +1053,9 @@ filtering_update_settings_1: |-
     -H 'Content-Type: application/json' \
     --data-binary '[
       "genres",
-      "director"
+      "director",
+      "release_date",
+      "ratings"
     ]'
 get_documents_post_1: |-
   curl \

config/redirects.json

@@ -51,7 +51,7 @@
   },
   {
     "source": "/docs/learn/advanced/sorting",
-    "destination": "/docs/learn/filtering_and_sorting/sorting",
+    "destination": "/docs/learn/filtering_and_sorting/sort_search_results",
     "permanent": true
   },
   {
@@ -378,5 +378,30 @@
     "source": "learn/configuration/settings",
     "destination": "reference/api/settings",
     "permanent": true
+  },
+  {
+    "source": "/docs/learn/fine_tuning_results/faceted_search",
+    "destination": "/docs/learn/filtering_and_sorting/search_with_facet_filters",
+    "permanent": true
+  },
+  {
+    "source": "/docs/learn/fine_tuning_results/filtering",
+    "destination": "/docs/learn/filtering_and_sorting/filter_search_results",
+    "permanent": true
+  },
+  {
+    "source": "/docs/learn/fine_tuning_results/working_with_dates",
+    "destination": "/docs/learn/filtering_and_sorting/working_with_dates",
+    "permanent": true
+  },
+  {
+    "source": "/docs/learn/fine_tuning_results/geosearch",
+    "destination": "/docs/learn/filtering_and_sorting/geosearch",
+    "permanent": true
+  },
+  {
+    "source": "/docs/learn/fine_tuning_results/sorting",
+    "destination": "/docs/learn/filtering_and_sorting/sort_search_results",
+    "permanent": true
   }
 ]

config/sidebar-learn.json

@@ -193,33 +193,38 @@
     ]
   },
   {
-    "title": "Fine-tuning results",
-    "slug": "fine_tuning_results",
+    "title": "Filtering and sorting",
+    "slug": "filtering_and_sorting",
     "routes": [
       {
-        "source": "learn/fine_tuning_results/faceted_search.mdx",
-        "label": "Faceted search",
-        "slug": "faceted_search"
+        "source": "learn/filtering_and_sorting/filter_search_results.mdx",
+        "label": "Filter search results",
+        "slug": "filter_search_results"
       },
       {
-        "source": "learn/fine_tuning_results/filtering.mdx",
-        "label": "Filtering",
-        "slug": "filtering"
+        "source": "learn/filtering_and_sorting/search_with_facet_filters.mdx",
+        "label": "Search with facet filters",
+        "slug": "search_with_facet_filters"
       },
       {
-        "source": "learn/fine_tuning_results/working_with_dates.mdx",
-        "label": "Filtering and sorting by date",
+        "source": "learn/filtering_and_sorting/working_with_dates.mdx",
+        "label": "Filter and sort by date",
         "slug": "working_with_dates"
       },
       {
-        "source": "learn/fine_tuning_results/geosearch.mdx",
+        "source": "learn/filtering_and_sorting/sort_search_results.mdx",
+        "label": "Sort search results",
+        "slug": "sort_search_results"
+      },
+      {
+        "source": "learn/filtering_and_sorting/geosearch.mdx",
         "label": "Geosearch",
         "slug": "geosearch"
       },
       {
-        "source": "learn/fine_tuning_results/sorting.mdx",
-        "label": "Sorting",
-        "slug": "sorting"
+        "source": "learn/filtering_and_sorting/filter_expression_reference.mdx",
+        "label": "Filter expression reference",
+        "slug": "filter_expression_reference"
       }
     ]
   },

guides/indexing_best_practices.mdx

@@ -14,7 +14,7 @@ To speed up indexing, review your list of [searchable attributes](/learn/relevan
 
 ### Review filterable and sortable attributes
 
-Some document fields are necessary for [filtering](/learn/fine_tuning_results/filtering) and [sorting](/learn/fine_tuning_results/sorting) results, but they dot not need to be _searchable_. Generally, **numeric and boolean fields** fall into this category. Make sure to review your list of searchable attributes and remove any fields that are only used for filtering or sorting.
+Some document fields are necessary for [filtering](/learn/filtering_and_sorting/filter_search_results) and [sorting](/learn/filtering_and_sorting/sort_search_results) results, but they dot not need to be _searchable_. Generally, **numeric and boolean fields** fall into this category. Make sure to review your list of searchable attributes and remove any fields that are only used for filtering or sorting.
 
 ## Set ranking rules before indexing
 

guides/laravel_scout.mdx

@@ -133,7 +133,7 @@ class Contact extends Model
 
 ## Configuring filterable and sortable attributes
 
-Configure which attributes are [filterable](/learn/fine_tuning_results/filtering) and [sortable](/learn/fine_tuning_results/sorting) via your Meilisearch index settings.
+Configure which attributes are [filterable](/learn/filtering_and_sorting/filter_search_results) and [sortable](/learn/filtering_and_sorting/sort_search_results) via your Meilisearch index settings.
 
 In Laravel, you can configure your index settings via the `config/scout.php` file:
 
@@ -182,7 +182,7 @@ You built an example application to demonstrate how to use Meilisearch with Lara
 This demo application uses the following features:
 - [Multi-search](/reference/api/multi_search) (search across multiple indexes)
 - [Multi-tenancy](/learn/security/multitenancy_tenant_tokens)
-- [Filtering](/learn/fine_tuning_results/filtering)
-- [Sorting](/learn/fine_tuning_results/sorting)
+- [Filtering](/learn/filtering_and_sorting/filter_search_results)
+- [Sorting](/learn/filtering_and_sorting/sort_search_results)
 
 Of course, the code is open-sourced on [Github](https://github.com/meilisearch/saas-demo). 🎉

learn/core_concepts/documents.mdx

@@ -37,7 +37,7 @@ If a field contains an object, Meilisearch flattens it during indexing using dot
 With [ranking rules](/learn/relevancy/ranking_rules), you can decide which fields are more relevant than others. For example, you may decide recent movies should be more relevant than older ones. You can also designate certain fields as displayed or searchable.
 
 <Capsule intent="note" title="Reserved attributes">
-Some features require Meilisearch to reserve attributes. For example, to use [geosearch functionality](/learn/fine_tuning_results/geosearch) your documents must include a `_geo` field.
+Some features require Meilisearch to reserve attributes. For example, to use [geosearch functionality](/learn/filtering_and_sorting/geosearch) your documents must include a `_geo` field.
 
 Reserved attributes are always prefixed with an underscore (`_`).
 </Capsule>

learn/core_concepts/indexes.mdx

@@ -99,15 +99,15 @@ Facets are a specific use-case of filters in Meilisearch: whether something is a
 
 By default, Meilisearch returns `100` facet values for each faceted field. You can change this using the [update settings endpoint](/reference/api/settings#update-settings) or the [update faceting settings endpoint](/reference/api/settings#update-faceting-settings).
 
-[Learn more about faceting.](/learn/fine_tuning_results/faceted_search)
+[Learn more about faceting.](/learn/filtering_and_sorting/search_with_facet_filters)
 
 ### Filterable attributes
 
 Filtering allows you to refine your search based on different categories. For example, you could search for all movies of a certain `genre`: `Science Fiction`, with a `rating` above `8`.
 
 Before filtering on any document attribute, you must add it to `filterableAttributes` using the [update settings endpoint](/reference/api/settings#update-settings) or the [update filterable attributes endpoint](/reference/api/settings#update-filterable-attributes). Then, make a search query using the [`filter` search parameter](/reference/api/search#filter).
 
-[Learn more about filtering.](/learn/fine_tuning_results/filtering)
+[Learn more about filtering.](/learn/filtering_and_sorting/filter_search_results)
 
 ### Pagination
 
@@ -129,7 +129,7 @@ By default, Meilisearch orders results according to their relevancy. You can alt
 
 Add the attributes you'd like to sort by to `sortableAttributes` using the [update settings endpoint](/reference/api/settings#update-settings) or the [update sortable attributes endpoint](/reference/api/settings#update-sortable-attributes). You can then use the [`sort` search parameter](/reference/api/search#sort) to sort your results in ascending or descending order.
 
-[Learn more about sorting.](/learn/fine_tuning_results/sorting)
+[Learn more about sorting.](/learn/filtering_and_sorting/sort_search_results)
 
 ### Stop words
 

learn/engine/datatypes.mdx

@@ -79,7 +79,7 @@ A numeric type (`integer`, `float`) is converted to a human-readable decimal num
 
 You can add [custom ranking rules](/learn/relevancy/custom_ranking_rules) to create an ascending or descending sorting rule on a given attribute that has a numeric value in the documents.
 
-You can also create [filters](/learn/fine_tuning_results/filtering). The `>`, `>=`, `<`, `<=`, and `TO` relational operators apply only to numerical values.
+You can also create [filters](/learn/filtering_and_sorting/filter_search_results). The `>`, `>=`, `<`, `<=`, and `TO` relational operators apply only to numerical values.
 
 ## Boolean
 

learn/filtering_and_sorting/facet_types.mdx

@@ -0,0 +1,62 @@
+---
+title: Faceted search — Meilisearch documentation
+description: Faceted search interfaces provide users with a quick way to narrow down search results by selecting categories relevant to their query.
+sidebarDepth: 3
+---
+
+# Facet types
+
+## Conjunctive facets
+
+Conjunctive facets use the `AND` logical operator. When users select multiple values for a facet, returned results must contain all selected facet values.
+
+With conjunctive facets, when a user selects `English` from the `language` facet, all returned books must be in English. If the user further narrows down the search by selecting `Fiction` and `Literature` as `genres`, all returned books must be in English and contain both `genres`.
+
+```
+"language = English AND genres = Fiction AND genres = Literature"
+```
+
+The GIF below shows how the facet count for `genres` updates to only include books that meet **all three conditions**.
+
+![Selecting English books with 'Fiction' and 'Literature' as 'genres' for the books dataset](/assets/images/faceted-search/conjunctive-factes.gif)
+
+## Disjunctive facets
+
+Disjunctive facets use the `OR` logical operator. When users select multiple values for a facet, returned results must contain at least one of the selected values.
+
+With disjunctive facets, when a user selects `Fiction`, and `Literature`, Meilisearch returns all books that are either `Fiction`, `Literature`, or both:
+
+```
+"genres = Fiction OR genres = Literature"
+```
+
+The GIF below shows the `books` dataset with disjunctive facets. Notice how the facet count for `genres` updates based on the selection.
+
+![Selecting 'Fiction' and 'Literature' as 'genres' for the books dataset](/assets/images/faceted-search/disjunctive_facets.gif)
+
+### Combining conjunctive and disjunctive facets
+
+It is possible to create search queries with both conjunctive and disjunctive facets.
+
+For example, a user might select `English` and `French` from the `language` facet so they can see books written either in English or in French. This query uses an `OR` operator and is a disjunctive facet:
+
+```
+"language = English OR language = French"
+```
+
+The same user might also be interested in literary fiction books and select `Fiction` and `Literature` as `genres`. Since the user wants a specific combination of genres, their query uses an `AND` operator:
+
+```
+"genres = Fiction AND genres = Literature"
+```
+
+The user can combine these two filter expressions in one by wrapping them in parentheses and using an `AND` operator:
+
+```
+"(language = English OR language = French) AND (genres = Fiction AND genres = Literature)"
+```
+
+The GIF below shows the `books` dataset with conjunctive and disjunctive facets. Notice how the facet count for each facet updates based on the selection.
+
+![Selecting 'Fiction' and 'Literature' as 'genres' for English books](/assets/images/faceted-search/conjunctive-and-disjunctive-facets.gif)
+

learn/filtering_and_sorting/facets_vs_filters.mdx

@@ -0,0 +1,27 @@
+---
+title: Faceted search — Meilisearch documentation
+description: Faceted search interfaces provide users with a quick way to narrow down search results by selecting categories relevant to their query.
+sidebarDepth: 3
+---
+
+You can use Meilisearch filters to build faceted search interfaces. This type of interface allows users to refine search results based on broad categories or facets. Faceted search provides users with a quick way to narrow down search results by selecting categories relevant to what they are looking for. A faceted navigation system is an **intuitive interface to display and navigate through content**.
+
+Facets are common in ecommerce sites like Amazon. When users search for products, they are presented with a list of results and a list of facets which you can see on the sidebar in the image below:
+
+[![Meilisearch demo for an ecommerce website displaying faceting UI](/assets/images/faceted-search/facets-ecommerce.png)](https://ecommerce.meilisearch.com/?utm_campaign=oss&utm_source=docs&utm_medium=faceted-search&utm_content=image)
+
+Faceted search interfaces often have a count of how many results belong to each facet. This gives users a visual clue of the range of results available for each facet.
+
+### Filters or facets
+
+Meilisearch does not differentiate between facets and filters. Facets are a specific use-case of filters, meaning you can use any attribute added to `filterableAttributes` as a facet. Whether something is a filter or a facet depends above all on UX and UI design.
+
+## Example application
+
+The Meilisearch ecommerce demo makes heavy use of faceting features to enable:
+- Filtering products by category and brand
+- Filtering products by price range and rating
+- Searching through facet values (e.g. category)
+- Sorting facet values (count or alphabetical order)
+
+Check out the [ecommerce demo](https://ecommerce.meilisearch.com/?utm_campaign=oss&utm_source=docs&utm_medium=faceted-search&utm_content=link) and the [GitHub repository](https://github.com/meilisearch/ecommerce-demo/).