> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# Method name: facets()

# Method package: wixSearch

# Method menu location: wixSearch --> WixSearchResult --> facets

# Method Link: https://dev.wix.com/docs/velo/apis/wix-search/wix-search-result/facets.md

# Method Description:

Returns the facet results retrieved by the search.

The facet results provide grouping information 
 for documents returned by the search, based on the requested facets.
 
 Facet results are structured as follows:

 Each facet specified in the [`facets()`](wix-search.WixSearchBuilder.html#facets) function returns
 a single facet result. Each facet result includes a facet group containing the name of the specified facet 
 and an array of facets listing the number of documents matching each facet value.
 
 The following example shows the facet results for a store product search for which `collections` 
 and `onSale` were specified as facets:

 ```javascript
"facets": 
  [
    {
      "facet": "collections",
      "facets": 
        [
          {
            "facetValue": "Boots",
            "count": 13
          },
          {
            "facetValue": "Running Shoes",
            "count": 22
          },
          {
            "facetValue": "Sandals",
            "count": 18
          }
        ]
    },
    {
      "facet": "onSale",
      "facets": 
        [
          {
            "facetValue": "true",
            "count": 17
          },
          {
            "facetValue": "false",
            "count": 36
          }
        ]
    }
  ]
 ```
 

 When no facets are specified in the [`facets()`](wix-search.WixSearchBuilder.html#facets) function, 
 the returned `facets` array is empty.



# Method Code Examples:

*** Note: do not assume any prop names or enum values other than the ones in the example.

## Create a search with facets, run the search, and get the facet results

```javascript
import wixSearch from 'wix-search';

// ...

wixSearch.search()
  .documentType("Stores/Products")
  .facets("collections", "inStock")
  .find()
  .then( (results) => {
    const facets = results.facets;
  })
  .catch( (error) => {
    console.log(error);
  });

 /* Example facets array
  * 
  * [
  *   {
  *     "facet": "collections",
  *     "facets":
  *       [
  *         {
  *           "facetValue": "Winter",
  *           "count": 29
  *         },
  *         {
  *           "facetValue": "Spring",
  *           "count": 17
  *         },
  *         {
  *           "facetValue": "Summer",
  *           "count": 36
  *         }
  *       ]
  *   },
  *   {
  *     "facet": "inStock",
  *     "facets":
  *       [
  *         {
  *           "facetValue": "true",
  *           "count": 67
  *         },
  *         {
  *           "facetValue": "false",
  *           "count": 15
  *         }
  *       ]
  *   }
  * ]
  * 
  */
```

## Filter search results according to a selected facet

```javascript
import wixSearch from 'wix-search';

$w.onReady(function () {

  // Define what happens when the facet repeater's data is set
  $w("#facetRepeater").onItemReady(($item, itemData) => {
    $item("#facetText").text = itemData.facetValue;
    $item("#facetNumberText").text = "(" + itemData.count + ")";

    // When a facet is selected, run the function
    // that displays only the selected products
    $item("facetText").onClick(event => {
      const facet = $item("#facetText").text;
      displaySelectedProducts(facet);
    });
  });

  // Define what happens when the product repeater's data is set
  $w("productRepeater").onItemReady(($item, itemData) => {
    $item("#productTitleText").text = itemData.title;
    $item("#productDescriptionText").text = itemData.description;
    $item("#productImage").src = itemData.image;
  });
  
  // Run a search which applies a facet that categorizes store
  // products according to the collection they belong to
  wixSearch.search()
  .documentType("Stores/Products")
  .facets("collections")
  .find()
  .then((results) => {

      // Get the first (and only) facet result
      const facets = results.facets[0].facets;

      // Add an ID to each object in the facets 
      // array (required for repeater data)
      const newFacets = facets.map((facet) => {
        facet._id = facet.facetValue;
        return facet;
      });
      
      // Set the facet repeater's data
      $w('#facetRepeater').data = newFacets;
      // Set the initial pre-filtered product repeater's data 
      $w('#productRepeater').data = results.documents;
    });
});

// Display only products from the collection 
// corresponding to the selected facet
export function displaySelectedProducts(facet) {
  wixSearch.search()
  .documentType("Stores/Products")
  .hasSome("collections", [facet])
  .find()
  .then((results) => {
    $w('#productRepeater').data = results.documents;
  });
}
```

---