> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Faceted and Textual Search

Plan: Developer Foundations

Lesson 17 of 28 · 30 min

## Overview

BigCommerce's GraphQL Storefront API lets merchants on headless storefronts use faceted and textual search powered by results from our back-end search engine. These built-in capabilities also allow Stencil developers to take advantage of our search engine.

**Faceted search** is a method of helping shoppers navigate a store's product inventory by categorizing products into various categories, brands, product features, and more.

**Textual search** is a method of retrieving products based on product fields, for example, product name and description.

## Faceted and Textual Search Features

The GraphQL Storefront API's faceted and textual search lets you create the following features:

* Load category pages with no selections, including both the facets and products relevant to the search results.
* Load category pages with facet selections for specific facets.
* Load featured products from specific categories.
* Quickly search products by using search terms (textual search).
* Sort products alphabetically, from newest to oldest and more.

> **Info**
>
> **Note**
>
> You can query facets, filter by rating, or filter by "in-stock" only if the merchant is on a Scale or Performance plan. A merchant must [enable product filtering](https://support.bigcommerce.com/s/article/Product-Filtering-Settings?language=en_US#setup) for facets to be returned.
>
> In addition, only facets that a merchant marks as visible in their Product Filtering settings will be returned.

## Filter Products and Facets

To use faceted and textual search, specify a filter in the argument for `SearchProducts`. For *faceted search*, you can filter by price, rating, among other features and attributes of products. For *textual search*, use the `searchTerm` field.

The filters below affect **both** the products and facets that are returned. For example, filtering by rating returns only products within the specified rating range and only facets that have products within the rating range.

```graphql showLineNumbers={false}
...
  searchProducts(
  filters: {
    searchTerm: "Sample"
    price:{
      minPrice:11,
      maxPrice:200
    },
    rating:{
      minRating:3,
      maxRating:5
    },
    categoryEntityId:24,
    searchSubCategories:false,
    categoryEntityIds:[23],
    brandEntityIds:[35],
    productAttributes:[
      {
        attribute:"Color",
        values:["Black"]
      }
    ],
    isFreeShipping:true,
    isFeatured:true,
    isInStock:true
  }
  ...
) {
...
```

## Get Products

To get products, specify products as a field in `searchProducts`.

Below is an example request that returns the first two products with a rating between three and five:

#### Query

```graphql showLineNumbers={false}
query {
  site {
    search {
      searchProducts(
        filters: {
          rating:{
             minRating:3,
             maxRating:5
           }
        }
      ) {
        products(first: 2) {
          edges {
            node {
              entityId
              name
              prices {
                price {
                  value
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### Response

```json showLineNumbers={false}
{
  "data": {
    "site": {
      "search": {
        "searchProducts": {
          "products": {
            "edges": [
              {
                "node": {
                  "entityId": 80,
                  "name": "[Sample] Orbit Terrarium - Large",
                  "prices": {
                    "price": {
                      "value": 109
                    }
                  }
                }
              },
              {
                "node": {
                  "entityId": 93,
                  "name": "[Sample] 1 L Le Parfait Jar",
                  "prices": {
                    "price": {
                      "value": 7
                    }
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}
```

## Sort Results

You can sort the products that are returned using the sort field. The sort affects only the list of products returned. The product filtering settings determine how facets are sorted.

Below is an example query that searches for products using a search term and sorts the returned products in alphabetical order:

#### Query

```graphql showLineNumbers={false}
query {
  site {
    search {
      searchProducts(
        filters: {
          searchTerm: "Sample"
        }
        sort: A_TO_Z
      ) {
        products(first: 2) {
          edges {
            node {
              entityId
              name
              prices {
                price {
                  value
                }
              }
            }
          }
        }
      }
    }
  }
}
```

#### Response

```json showLineNumbers={false}
{
  "data": {
    "site": {
      "search": {
        "searchProducts": {
          "products": {
            "edges": [
              {
                "node": {
                  "entityId": 93,
                  "name": "[Sample] 1 L Le Parfait Jar",
                  "prices": {
                    "price": {
                      "value": 7
                    }
                  }
                }
              },
              {
                "node": {
                  "entityId": 86,
                  "name": "[Sample] Able Brewing System",
                  "prices": {
                    "price": {
                      "value": 225
                    }
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}
```

> **Info**
>
> For a list of product fields that searchTerm searches, see the [Store Search Product Fields](https://support.bigcommerce.com/s/article/Store-Search?language=en_US#best-practices) article.

## Get Facets

To get facets, specify `filters` as a field in `searchProducts`.

Below is an example request that returns the specified facets that have products with a rating between three and five:

#### Query

```graphql showLineNumbers={false}
query {
  site {
    search {
      searchProducts(
        filters: {
           rating:{
             minRating:3,
             maxRating:5
           }
        }
      ) {
         filters {
           edges {
             node {
               __typename
               name
               isCollapsedByDefault
               ... on CategorySearchFilter {
                 name
                 displayProductCount
                 isCollapsedByDefault
                 categories {
                   edges {
                     node {
                       entityId
                       isSelected
                       productCount
                       subCategories {
                         edges {
                           node {
                             entityId
                             name
                           }
                         }
                       }
                     }
                   }
                 }
               }
               ... on OtherSearchFilter {
                 name
                 displayProductCount
                 isCollapsedByDefault
                 freeShipping {
                   isSelected
                   productCount
                 }
                 isInStock {
                   isSelected
                   productCount
                 }
                 isFeatured {
                   isSelected
                   productCount
                 }
               }
             }
           }
         }
      }
    }
  }
}
```

#### Response

```json showLineNumbers={false}
{
  "data": {
    "site": {
      "search": {
        "searchProducts": {
          "filters": {
            "edges": [
              {
                "node": {
                  "__typename": "CategorySearchFilter",
                  "name": "Category",
                  "isCollapsedByDefault": false,
                  "displayProductCount": true,
                  "categories": {
                    "edges": [
                      {
                        "node": {
                          "entityId": 19,
                          "isSelected": false,
                          "productCount": 1,
                          "subCategories": {
                            "edges": []
                          }
                        }
                      },
                      {
                        "node": {
                          "entityId": 21,
                          "isSelected": false,
                          "productCount": 1,
                          "subCategories": {
                            "edges": []
                          }
                        }
                      }
                    ]
                  }
                }
              },
              {
                "node": {
                  "__typename": "OtherSearchFilter",
                  "name": "Other",
                  "isCollapsedByDefault": true,
                  "displayProductCount": true,
                  "freeShipping": null,
                  "isInStock": {
                    "isSelected": false,
                    "productCount": 2
                  },
                  "isFeatured": null
                }
              }
            ]
          }
        }
      }
    }
  }
}
```

For a complete list of facets, see the [GraphQL Storefront Playground](/developer/docs/storefront/guides/graphql-storefront-api/overview).

## Put It All Together: Get Products and Facets

To get both products and facets, specify both `products` and `filters` fields in `searchProducts`.

#### Query

```graphql showLineNumbers={false}
query {
  site {
    search {
      searchProducts(
        filters: {
          searchTerm: "Sample"
           rating:{
             minRating:3,
             maxRating:5
           }
        }
        sort: A_TO_Z
      ) {
        products(first: 2) {
          edges {
            node {
              entityId
              name
              prices {
                price {
                  value
                }
              }
            }
          }
        }
         filters {
           edges {
             node {
               __typename
               name
               isCollapsedByDefault
               ... on CategorySearchFilter {
                 name
                 displayProductCount
                 isCollapsedByDefault
                 categories {
                   edges {
                     node {
                       entityId
                       isSelected
                       productCount
                       subCategories {
                         edges {
                           node {
                             entityId
                             name
                           }
                         }
                       }
                     }
                   }
                 }
               }
               ... on OtherSearchFilter {
                 name
                 displayProductCount
                 isCollapsedByDefault
                 freeShipping {
                   isSelected
                   productCount
                 }
                 isInStock {
                   isSelected
                   productCount
                 }
                 isFeatured {
                   isSelected
                   productCount
                 }
               }
             }
           }
         }
      }
    }
  }
}
```

#### Response

```json showLineNumbers={false}
{
    "data": {
      "site": {
        "search": {
          "searchProducts": {
            "products": {
              "edges": [
                {
                  "node": {
                    "entityId": 93,
                    "name": "[Sample] 1 L Le Parfait Jar",
                    "prices": {
                      "price": {
                        "value": 7
                      }
                    }
                  }
                },
                {
                  "node": {
                    "entityId": 80,
                    "name": "[Sample] Orbit Terrarium - Large",
                    "prices": {
                      "price": {
                        "value": 109
                      }
                    }
                  }
                }
              ]
            },
            "filters": {
              "edges": [
                {
                  "node": {
                    "__typename": "CategorySearchFilter",
                    "name": "Category",
                    "isCollapsedByDefault": false,
                    "displayProductCount": true,
                    "categories": {
                      "edges": [
                        {
                          "node": {
                            "entityId": 19,
                            "isSelected": false,
                            "productCount": 1,
                            "subCategories": {
                              "edges": []
                            }
                          }
                        },
                        {
                          "node": {
                            "entityId": 21,
                            "isSelected": false,
                            "productCount": 1,
                            "subCategories": {
                              "edges": []
                            }
                          }
                        }
                      ]
                    }
                  }
                },
                {
                  "node": {
                    "__typename": "OtherSearchFilter",
                    "name": "Other",
                    "isCollapsedByDefault": true,
                    "displayProductCount": true,
                    "freeShipping": null,
                    "isInStock": {
                      "isSelected": false,
                      "productCount": 2
                    },
                    "isFeatured": null
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
```

If product filtering has not been enabled, you will receive an empty array for the returned facets, though products will still be returned. To enable product filtering, refer to the KB Article below:

* [Product Filtering](https://support.bigcommerce.com/s/article/Product-Filtering-Settings)

## Resources

* [Faceted and Textual Search with the GraphQL Storefront API](/developer/docs/storefront/headless/products/faceted-textual-search)
* [GraphQL Storefront Playground](/developer/docs/storefront/guides/graphql-storefront-api/overview)
* [Store Search Product Fields](https://support.bigcommerce.com/s/article/Store-Search?language=en_US#best-practices)
* [Product Filtering](https://support.bigcommerce.com/s/article/Product-Filtering-Settings)