Get started with NeuralSearch

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.

Before you begin

This feature isn’t available on every plan. Refer to your pricing plan to see if it’s included.

To get started, your index must contain records. 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

Go to the Algolia dashboard and select your Algolia .
On the left sidebar, select Search.
Select your index.
Click the NeuralSearch tab.
Click Configure NeuralSearch.
Select the source index for events.
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.

Building the NeuralSearch index can take longer for larger datasets.

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.

Run a query and look for results with a blue Vector badge: these were retrieved by vector search.
Click a result, then click the compass icon to open its details.
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:

Retrieval
Tie-breaking
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, 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 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.

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

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.

Base URL

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:

Command line

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.

Command line

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.
`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.
`usePositionalSemanticRanking`	`boolean`	When `true`, vector results use Algolia’s standard tie-breaking algorithm. See 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

​Before you begin

​Activate NeuralSearch

​Preview your results

​Compare results

​Inspect vector results

​Understand search result changes

​How NeuralSearch ranks results

​Retrieve results

​Apply tie-breaking

​Merge results

​Configure presets

​Semantic Precision

​Configure NeuralSearch with the semantic settings endpoint

​Retrieve settings

​Update settings

​Parameters

​Positional semantic ranking

​See also

Before you begin

Activate NeuralSearch

Preview your results

Compare results

Inspect vector results

Understand search result changes

How NeuralSearch ranks results

Retrieve results

Apply tie-breaking

Merge results

Configure presets

Semantic Precision

Configure NeuralSearch with the semantic settings endpoint

Retrieve settings

Update settings

Parameters

Positional semantic ranking

See also