> ## Documentation Index
> Fetch the complete documentation index at: https://www.algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Query Categorization
> Predict the categories to which a search query belongs with AI.
export const Records = () =>
records
;
export const Index = () =>
index
;
export const AcademyLink = ({href, title}) => {
return Learn more about: {title};
};
This feature isn't available on every plan.
Refer to your [pricing plan](https://www.algolia.com/pricing) to see if it's included.
The Query Categorization feature uses an AI model to predict the appropriate category for a search query.
It predicts the most likely category for a query based on past search and click and conversion data.
For example, the query "banana" might be categorized under "Food > Fruits."
Query Categorization also groups similar queries into categories.
For example, both "blue jeans" and "denim" could be classified in the "Clothing > Pants" category.
"Denim" could also belong to the "Clothing" category.
## Features
**Query Categorization** gives you access to these features:
* **Dashboard control** lets you set up and check AI model predictions from the Algolia dashboard.
* **Automatic filtering and boosting** improves the relevance of results without writing code.
* **Category predictions:** use the Search API to generate real-time category predictions for user queries. Use these predictions to customize their search and discovery experience.
## Set up Query Categorization
To get started with Query Categorization:
1. **[Send click and conversion data](#send-click-and-conversion-events)** to Algolia: this helps the AI model learn user behavior.
2. **[Create a facet hierarchy](#create-a-facet-hierarchy)** to define the categories and subcategories your belong to. This lets the AI model classify them.
After setup, the [AI model](#the-ai-model) analyzes popular queries and categorizes them.
It also predicts categories for new queries.
### Send click and conversion events
To train the AI model, you must [send click or conversion events](/doc/guides/sending-events) to Algolia.
The model uses this data to predict the categories for new queries.
For a query to be eligible for Query Categorization model training, it must:
* Be longer than three characters
* Have returned at least 10 records
* Have received events for at least three different records.
The model is re-trained every 24 hours, using data from the last 90 days.
### Create a facet hierarchy
To enable Query Categorization, use the [dashboard](https://dashboard.algolia.com/query-categorization/) to define the facets.
These are the categories and subcategories the AI model uses.
These facets should accurately represent your data hierarchy, up to five levels deep.
Once you've entered your facets, click **Save** to start the model-building process.
Depending on the number of categories and traffic, this can take several minutes to half an hour.
#### Example facet hierarchy of nested categories
Assuming a record structure like this:
```json JSON icon=braces theme={"system"}
{
"name": "banana",
"description": "...",
"price": 3.45,
"hierarchicalCategories":
{
"lvl0": "Food",
"lvl1": "Fruits"
}
}
```
Set `hierarchicalCategories.lvl0` as the first level used by the model and `hierarchicalCategories.lvl1` as the second level.
#### Example facet hierarchy of flat categories
Assuming a record structure like this:
```json JSON icon=braces theme={"system"}
{
"name": "banana",
"description": "...",
"price": 3.45,
"group": "Food",
"section": "Fruits"
}
```
Set `group` as the first level used by the model and `section` as the second level.
Your records might belong to several categories at the same time.
If you use arrays to represent each level of depth, the model expects shared prefixes.
For example, `Food` is the first level facet value and `Food > Fruits` is the second level.
#### Unsupported hierarchical facet formats
The model doesn't support records structured with only one attribute for all depth levels.
For example:
```json JSON icon=braces theme={"system"}
{
"name": "banana",
"description": "...",
"price": 3.45,
"categories": ["Food", "Food > Fruits"]
}
```
### Manage categories
After model training, view the generated categories tree.
Find it in the **Categories Tree View** tab in the [dashboard](https://dashboard.algolia.com/query-categorization/).
This lets you review and adjust the structure as needed.
#### Exclude categories
From the **Categories Tree View** tab,
you can also exclude non-categories like "Black Friday" or "On sale" to increase the model's accuracy.
### Manage events source
You can use different data sources for your events.
For example, use data from a production to improve predictions for a test index that hasn't had any user interactions.
To use a different data source:
1. Go to the **Categories Setting** tab in the [dashboard](https://dashboard.algolia.com/query-categorization/).
2. In **Events source index**, select the new data source (it must be a [replica](/doc/guides/managing-results/refine-results/sorting/in-depth/replicas) or a copy of the existing source index).
3. Click **Save** to regenerate the category tree and make predictions using events from the new data source.
## The AI model
After the facet hierarchy has been saved, the AI model performs these tasks:
1. Build a "categories tree" based on your data.
2. Identify top categories for popular queries.
3. Predict categories for new queries.
### Model output
The AI model assigns a confidence level and a type to each prediction:
* **Confidence level:** `very low`, `low`, `high`, `very high`, or `certain`.
* **Type:**
* `narrow`: the query matches a specific category.
* `broad`: the query matches a category with subcategories.
* `ambiguous`: the query matches several unrelated categories.
* `none`: the model can't determine a category.
## Use predictions at query time
Use Query Categorization predictions to enhance search results in your frontend at query time to:
* **Expand results:** if results are limited, expand them. Add more items from the same category.
* **Refine broad search terms:** if a query is classified as `broad`, suggest different categories. This helps users narrow their search.
* **Customize search**: offer a tailored search experience by providing a specific layout for some categories.
Query Categorization populates your search results with the predicted categories for the search query.
[Algolia normalizes](/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp#normalization) the query used for prediction, not the raw query.
### Turn on Query Categorization at query time
To retrieve Query Categorization results at query time, activate the option from the dashboard or in query parameters.
* **In the [dashboard](https://dashboard.algolia.com/query-categorization/)**, enable the **Categories with Search API** toggle in the **Categories Settings** tab.
* **In query parameters** as a JSON object or a [URL encoded string](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).
For example, `extensions%3D%7B%22queryCategorization%22%3A%7B%22enableCategoriesRetrieval%22%3Atrue%7D%7D`
Find Query Categorization parameters in the `extensions` field:
```jsonc JSON icon=braces theme={"system"}
{
// Other standard query parameters
"extensions": {
"queryCategorization": {
"enableCategoriesRetrieval": true
// Other options to control automatic filtering and boosting are available
}
}
}
```
#### Search response format
The [search response](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response) shows predictions in the attribute `extensions.queryCategorization`.
```jsonc JSON icon=braces theme={"system"}
{
// Regular search answer (like hits)
"extensions": {
"queryCategorization": {
"normalizedQuery": "banana",
"count": 2,
"type": "narrow",
"categories": [
{
"bin": "very high",
"hierarchyPath": [
{
"facetName": "category.lvl0",
"facetValue": "Food",
"depth": 0
},
{
"facetName": "category.lvl1",
"facetValue": "Fruits",
"depth": 1
}
]
}
]
}
}
}
```
Sometimes, `extensions.queryCategorization` is empty if the Query Categorization model can't categorize a query.
## How to override predictions
You can override the AI model's predictions from the [dashboard's](https://dashboard.algolia.com/query-categorization/) **Predictions Explorer** tab.
* To change the override or replace the predicted categories, click the edit (pencil) icon.
* To revert an override to the predicted categories, click the zap (lightning) icon.
* To remove a prediction, click the trash icon.
Algolia displays changes in the predictions list.
To confirm them, click **Save changes** at the bottom of the page.
Changing the index classification in **Categories Settings** deletes any override affected by this change.
For example, removing the second facet level from the index classification deletes overrides like `Food > Fruits`,
reverting the query to automatic predictions.
## Automatic filtering and boosting
Automatic filtering and boosting applies filters for user queries based on Query Categorization predictions.
* **Automatic filtering** [filters out](/doc/guides/managing-results/refine-results/filtering/in-depth/filters-and-facetfilters) items that don't match the predicted category.
* **Automatic boosting** uses an [optional filter](/doc/guides/managing-results/rules/merchandising-and-promoting/in-depth/optional-filters) to boost items that match the predicted category.
This moves matching items to the top of search results.
Based on [confidence levels](#model-output), the Query Categorization model decides how to apply predictions.
It can apply them as filters, as boosts, or not at all.
### Use automatic filtering and boosting
To use this feature, click **Enable Automatic Filtering & Boosting**.
You'll find this option in the **Automatic filtering & boosting Settings** tab in the [dashboard](https://dashboard.algolia.com/query-categorization/).
By default, only automatic boosting is activated.
To enable automatic filtering, see [Configure automatic filtering and boosting](#configure-automatic-filtering-and-boosting).
Once activated, Algolia automatically adds boosts to your search parameters at query time.
This doesn't require frontend changes.
#### Exclude queries
From the **Automatic filtering & boosting Settings** tab,
you can also exclude queries that shouldn't be automatically filtered or boosted.
Anything specified here overrides your index's configuration.
### Configure automatic filtering and boosting
Adjust the impact of automatic filtering and boosting by modifying two parameters in the **Automatic filtering & boosting Settings** tab:
* The minimum expected confidence level for filtering
* The minimum expected confidence level for boosting
These parameters let you configure when to apply filters or boosts based on the predictions' [confidence levels](#model-output).
The feature:
* Boosts predictions with a confidence level equal to or above the boosting level, but below the filtering level.
* Filters predictions with a confidence level equal to or above the filtering level.
For instance, say the boosting confidence level is `high` and the filtering confidence level is `certain`.
Algolia then boosts `high` and `very high` predictions, and filters on `certain` predictions.
The confidence level for boosting must always be lower than the level for filtering.
Turn off filtering or boosting with the corresponding options.
### Override automatic filtering and boosting at query time
You can override the default configuration for automatic filtering and boosting with query parameters:
```jsonc JSON icon=braces theme={"system"}
{
// Other query parameters ...
"extensions": {
"queryCategorization": {
"enableAutoFiltering": true
}
}
}
```
To let users remove filters applied by automatic filtering and boosting, you must turn off automatic filters and boosts on the search query.
Target the query at your index.
Do this when users clear the automatic filter.
[Create an InstantSearch widget to handle this behavior](/doc/guides/building-search-ui/going-further/automatic-filtering/js).
### Detect the impact of automatic filtering and boosting at query time
When automatic filtering and boosting is active for a query, the `extensions.queryCategorization.autofiltering` section has the following content:
```jsonc JSON icon=braces theme={"system"}
{
// ... Regular search response (including hits) ...
"extensions": {
"queryCategorization": {
"normalizedQuery": "banana",
"count": 14870,
"type": "narrow",
"categories": [
{
"bin": "certain",
"hierarchyPath": [
{
"facetName": "categories.lvl0",
"facetValue": "Food",
"depth": 0
},
{
"facetName": "categories.lvl1",
"facetValue": "Food > Fruits",
"depth": 1
}
]
}
],
"autofiltering": {
"enabled": true,
"maxDepth": 5,
"facetFilters": [
[
"categories.lvl0:Food"
],
[
"categories.lvl1:Food > Fruits"
],
],
"optionalFilters": []
}
}
}
}
```
You can activate automatic filtering and boosting without it having an impact.
Other fields don't appear in your [search response](#search-response-format).
### Preview automatic filtering and boosting
You can preview automatic filtering and boosting for any index.
Find this preview in the **Automatic filtering & boosting Preview** tab of the [**Query categorization** section in the dashboard](https://dashboard.algolia.com/query-categorization/).
If you have category predictions for the selected index, you can preview results for any query with predicted categories.
This shows how automatic filtering and boosting affects results, without activating it on your production traffic.
The automatic filtering and boosting preview shows how promotion [rules](/doc/guides/managing-results/rules/rules-overview) and [Dynamic Re-Ranking](/doc/guides/algolia-ai/re-ranking) affect results.
You can turn these features off in the preview with the **Rules** and **Dynamic Re-Ranking** options.
### A/B test automatic filtering and boosting
You can use A/B testing to test automatic filtering and boosting on an index.
This helps you measure the effect on your search accurately.
To do this, open the [**Query Categorization**](https://dashboard.algolia.com/query-categorization/) page in the Algolia dashboard.
Then, select the **Automatic filtering & boosting Settings** tab and click **Launch an A/B test**.
## Analytics grouped by categories
After setting up the Query Categorization model, you can view queries grouped by their predicted categories.
Find this view in the dashboard's **Grouped Searches** tab, under **Observe > Analytics**.
This view doesn't include browsing queries:
"empty" queries generated when a user clicks a filter or other UI element.
Compare categories or click them to inspect their queries.
Algolia automatically flags queries with low click-through or conversion rates.
It labels them "underperforming" within each category.
For example, Algolia flags `blue jeans` and `denim` as belonging to the same category (`pants`).
Grouped analytics displays the performance of the category `pants`.
This aggregates data for `blue jeans`, `denim`, and other queries in the `pants` category.
You can then compare the performance of the two.
For example, the `pants` category's click-through rate is 10%, but the click-through rate for `blue jeans` is only 4%.
Algolia identifies `blue jeans` as underperforming.
You can improve the performance of the query by, for example, adding a synonym or a Rule.
With grouped analytics, you can combine your search analytics to uncover new insights.
This helps you optimize your search and discovery experience.
It simplifies search analysis.
It also helps manage the [long tail](https://wikipedia.org/wiki/Long_tail) of search queries.
## See also
To learn more, see these blog articles:
* [Query understanding](https://www.algolia.com/blog/product/query-understanding-101)
* [12 ways to improve your search (including Query Categorization)](https://www.algolia.com/blog/engineering/12-ways-to-improve-your-search-index)