> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with NeuralSearch

> Activate NeuralSearch to combine keyword and semantic search on your Algolia index.

export const Application = () => <Tooltip tip="An Algolia application is a self-contained environment with its own indices, configuration, and API keys. Applications don't share data or settings with each other.">
    application
  </Tooltip>;

export const AlgoliaSearch = () => <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 80 80" width="20" height="20" className="inline" fill="none" role="presentation" ariaLabel="Algolia Search">
    <circle cx="40" cy="32" r="28" fill="#5468FF"></circle>
    <rect x="30" y="22" width="20" height="20" rx="10" fill="#fff"></rect>
    <path d="M43 63.5 54.5 60l6 17h-12L43 63.5Z" fill="#36395A"></path>
  </svg>;

export const AcademyLink = ({href, title}) => {
  return <Card horizontal title="Algolia Academy" href={href} icon="square-play">Learn more about: {title}</Card>;
};

NeuralSearch adds vector search to your keyword search, then merges and ranks the results.
This means your index returns results that match concepts and intent, not just exact keywords.

<AcademyLink href="https://academy.algolia.com/pages/contentcatalog/training/0199aad2-7326-7367-a843-33f2a39a0206/overview" title="NeuralSearch: Fundamentals" />

## Before you begin

<Callout icon="credit-card" color="#c084fc">
  This feature isn't available on every plan.
  Refer to your [pricing plan](https://www.algolia.com/pricing) to see if it's included.
</Callout>

To get started, [your index must contain records](/doc/guides/sending-and-managing-data/send-and-update-your-data).

Click and conversion events aren't required.
If you have them, NeuralSearch uses them to choose which record attributes to use for vectors.
Without events, NeuralSearch selects attributes automatically from your record structure.

## Activate NeuralSearch

1. Go to the [Algolia dashboard](https://dashboard.algolia.com/explorer/browse) and select your Algolia <Application />.
2. On the left sidebar, select <AlgoliaSearch /> **Search**.
3. Select your index.
4. Click the **NeuralSearch** tab.
5. Click **Configure NeuralSearch**.
6. Select the source index for events.
7. Click **Train NeuralSearch**.

* **If your index has events**, NeuralSearch analyzes the relationships between queries, events, and records to select and weight the attributes that produce the most relevant vector representations.
* **If your index doesn't have events**, NeuralSearch automatically selects attributes from your record structure. For example, attributes such as `title`, `description`, `color`, or `category`. Once you have events, you can retrain NeuralSearch to use them.

<Info>
  Building the NeuralSearch index can take longer for larger datasets.
</Info>

## Preview your results

When training is complete, NeuralSearch enters **Preview** mode automatically.
In preview mode you can:

* Compare NeuralSearch and keyword results using the **Compare** tab
* Launch an A/B test to measure impact on real traffic
* Apply NeuralSearch to live traffic

### Compare results

Use the Compare tab to evaluate NeuralSearch result quality.
Go to the **NeuralSearch** tab in your index and click **Compare**.

The Compare tab shows:

* **Top queries:** queries from your analytics that you can click to run immediately in compare mode
* **No-result queries:** queries that return no results in keyword search, so you can see NeuralSearch's impact
* **Training coverage:** which queries NeuralSearch has trained on

Compare mode shows keyword and NeuralSearch results side by side.
Turn vector results on and off to isolate the impact of semantic search.
The graph between the two columns shows which results have been re-ranked or moved as a result of vector search:
lines crossing indicate records that shifted position.

### Inspect vector results

You can also inspect individual results in the **Index** tab.

1. Run a query and look for results with a blue **Vector** badge: these were retrieved by vector search.
2. Click a result, then click the compass icon to open its details.
3. Look for **Vector similarity:** a score between 0 and 1. Closer to 1 means a stronger semantic match.

## Understand search result changes

NeuralSearch expands what your index can match:

| Capability           | Keyword search                   | NeuralSearch                                                |
| -------------------- | -------------------------------- | ----------------------------------------------------------- |
| Retrieval            | Keyword matches                  | Keyword matches and semantic matches                        |
| Results              | Exact or similar keyword matches | Relevant results even when the query doesn't match keywords |
| Intent understanding | Limited                          | Infers intent from the query                                |

For example, a query for "something to keep coffee hot" can return "insulated travel mug",
even with no keyword overlap.

## How NeuralSearch ranks results

NeuralSearch ranks results in three stages:

1. Retrieval
2. Tie-breaking
3. Merge results

### Retrieve results

NeuralSearch retrieves keyword results and vector results independently.
Vector results are initially ordered by similarity:
how close the record's vector is to the query's vector.

### Apply tie-breaking

Tie-breaking is applied independently to each result list.

The keyword list goes through Algolia's full [tie-breaking algorithm](/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria), including textual relevance steps like typo tolerance, attribute ordering, and proximity.

The vector list uses a subset of tie-breaking steps, but only those that apply to non-textual relevance:

* Geographical distance
* Optional filters
* Custom ranking

Text-based tie-breaking steps don't apply to vector results.

### Merge results

NeuralSearch merges the ranked vector and keyword lists,
then normalizes their scores to a common scale so they can be combined.
The [presets](#configure-presets) determine final result order.

## Configure presets

Presets control how keyword and semantic results are blended.
NeuralSearch uses the `default` preset unless you configure otherwise.

| Preset           | Behavior                                                                                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `conservative`   | Semantic search activates only for queries that return no keyword results. This preset minimizes changes to existing keyword results and is a good starting point. |
| `expanded_reach` | Semantic search activates when keyword result counts are low.                                                                                                      |
| `append_only`    | Semantic results are appended after all keyword results.                                                                                                           |
| `default`        | Semantic search runs on every query and blends with keyword results, with keyword results taking priority.                                                         |
| `custom`         | Lets you configure `semanticBlendWeight`, `minHitsForSemantic`, and `enableNeuralSearchSortBy`.                                                                    |

Configure presets with the [`semanticSearch/settings` API endpoint](#configure-neuralsearch-with-the-semantic-settings-endpoint).

## Semantic Precision

NeuralSearch retrieves up to 100 vector results per query by default.
Semantic Precision lets you control the trade-off between precision and recall by filtering those results based on similarity.

Configure Semantic Precision in your NeuralSearch settings.
Choose from these options:

| Setting                   | Behavior                                                                                     |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| **More Recall** (default) | Allows a broader set of results, including broader semantic matches.                         |
| **Balanced**              | A midpoint between recall and precision.                                                     |
| **More Precision**        | Filters out results with lower similarity scores, keeping only the closest semantic matches. |

To configure Semantic Precision with the API, see [`semanticSearch/settings`](#configure-neuralsearch-with-the-semantic-settings-endpoint).

## Configure NeuralSearch with the semantic settings endpoint

The semantic settings endpoint gives you programmatic control over NeuralSearch configuration for an index.
Use it to set presets, adjust blending behavior, configure Semantic Precision filtering, and configure positional ranking.

Changes take effect immediately. No reindexing is required unless you change `neuralExpression` or `vectorModelId`.

```txt Base URL theme={"system"}
https://{ALGOLIA_APPLICATION_ID}.algolia.net/1/indexes/{INDEX_NAME}/semanticSearch/settings
```

### Retrieve settings

To inspect the current NeuralSearch configuration for an index, send a `GET` request to the `semanticSearch/settings` endpoint:

```sh Command line icon=square-terminal theme={"system"}
curl --request GET \
  --url https://{ALGOLIA_APPLICATION_ID}.algolia.net/1/indexes/{INDEX_NAME}/semanticSearch/settings \
  --header 'x-algolia-api-key: {ALGOLIA_ADMIN_API_KEY}' \
  --header 'x-algolia-application-id: {ALGOLIA_APPLICATION_ID}'
```

### Update settings

To update the NeuralSearch configuration for an index, send a `PUT` request to the `semanticSearch/settings` endpoint.

This example sets the NeuralSearch preset to `custom` and configures Semantic Precision.

```sh Command line expandable icon=square-terminal theme={"system"}
curl --request PUT \
  --url https://{ALGOLIA_APPLICATION_ID}.algolia.net/1/indexes/{INDEX_NAME}/semanticSearch/settings \
  --header 'content-type: application/json' \
  --header 'x-algolia-api-key: {ALGOLIA_ADMIN_API_KEY}' \
  --header 'x-algolia-application-id: {ALGOLIA_APPLICATION_ID}' \
  --data '{
    "neuralSearchPreset": "custom",
    "semanticBlendWeight": 0.5,
    "dynamicThreshold": {
      "enabled": true,
      "aggression": 0.3,
      "lowerLimit": 0.64,
      "upperLimit": 0.85
    }
  }'
```

### Parameters

| Parameter                      | Type      | Description                                                                                                                                                  |
| ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `neuralSearchMode`             | `string`  | `"active"`, `"preview"`, or `"inactive"`. Controls whether NeuralSearch is on for live traffic.                                                              |
| `neuralSearchPreset`           | `string`  | One of `"default"`, `"conservative"`, `"expanded_reach"`, `"append_only"`, or `"custom"`. For more information, see [Configure presets](#configure-presets). |
| `semanticBlendWeight`          | `float`   | `0.0001`–`0.999`. Relative weight given to semantic results. `custom` preset only.                                                                           |
| `minHitsForSemantic`           | `integer` | `0`–`20`. Minimum keyword results before semantic results are included. `custom` preset only.                                                                |
| `enableNeuralSearchSortBy`     | `boolean` | When `true`, index ranking and sorting settings apply to the full NeuralSearch result set. `custom` preset only.                                             |
| `dynamicThreshold`             | `object`  | Semantic Precision filter config. See [Semantic Precision](#semantic-precision).                                                                             |
| `usePositionalSemanticRanking` | `boolean` | When `true`, vector results use Algolia's standard tie-breaking algorithm. See [Positional semantic ranking](#positional-semantic-ranking).                  |

### Positional semantic ranking

By default, vector results are ranked by how closely they match the meaning of the query.
Algolia's ranking formula doesn't apply to them.

Setting `usePositionalSemanticRanking: true` in the semantic settings endpoint changes this behavior.
With positional ranking enabled:

* Geographical distance is factored into semantic result ranking
* Optional filters apply to vector results
* Custom ranking attributes affect the order of semantic results

## See also

* **Measure the impact.** Run an [A/B test](/doc/guides/ai-relevance/neuralsearch/ab-testing) to compare NeuralSearch against keyword search on real traffic before you enable it for all traffic.
* **Improve results for your top queries.** After you have enough engagement data, enable [Adaptive Intent](/doc/guides/ai-relevance/neuralsearch/adaptive-intent) to continuously learn from clicks and conversions.
* **Configure NeuralSearch with the API.** Use [`semanticSearch/settings`](#configure-neuralsearch-with-the-semantic-settings-endpoint) for programmatic control over presets, blending, and ranking behavior.
* **Understand what's not supported.** Review [Limitations](/doc/guides/ai-relevance/neuralsearch/limitations) before building on top of NeuralSearch.