<!-- The markdown copy of https://oppalerts.com/docs/the-data/how-semantic-search-works . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [The Data](https://oppalerts.com/docs/the-data/) / How Semantic Search Works

# How Semantic Search Works

Find pages about your subject, even when they use different words.

## Semantic similarity, not words

A keyword search finds pages containing your words. A semantic search finds pages about the same subject. A search for "reducing restaurant food waste" can find a page about "kitchen efficiency": the words differ, but the subjects are related.

## How it works

1. OppAlerts turns each document into a vector: a list of numbers that represents its subject.
2. Your search text is turned into a vector in the same way.
3. OppAlerts finds the documents with the nearest vectors.
4. Each result gets a similarity score from 0 to 100 percent, showing how close the vectors are.

## What the search compares with

- **Your own text:** Similarity text in the web app, `"similarity_target": "similarity_text"` with the text in `similarity_text` in MCP and the API. Write one to three sentences that describe the subject, with enough context to distinguish it from related subjects.
- **Your campaign:** a stored description of your market, based on AI model answers about your industry when the campaign was finalized. The type pages and many brand pages use it. In MCP and the API, send `"similarity_target": "campaign"`.
- **One document:** Similar News and Similar Prospects find the pages nearest to one result.

## The similarity score

- `similarity_score` is 0 to 100. It is the cosine similarity of the two vectors, times 100.
- It is `null` when the search had no vector (`"similarity_target": "none"`). It is never 0 for "no similarity".
- **Min similarity** excludes results below your chosen value. Advanced Search defaults to 30%, and the saved opportunity form also defaults to 30. In MCP and the API, the field is `similarity_score_min`, and it has no default.
- Consider the order of results and the gaps between them, alongside the score.

## Semantic similarity and words together

- Add **Title query** or **Body query** words. Every word you enter is required, unless an operator such as `OR` or `MAYBE` says otherwise. See [Advanced Search Operators](https://oppalerts.com/docs/the-data/advanced-search-operators).
- A page must then match the words, be at or above Min similarity, and pass every other filter.
- `relevance_weight` is the word-match weight. It has no upper limit: compare it only with other results in the same response.

## Limits

- A semantic search in the web app shows at most 100 rows. A call to an MCP or API search tool returns at most 1,000 rows, and at most 100 on a free account.
- It starts with a limited set of candidates, then filters and groups them. Changing your text can bring in different candidates and produce a new list.
- Finding no results does not mean nobody has written about the subject. Rephrase your text or lower Min similarity.

## Tips

- Describe the situation, not one keyword: "restaurants that cannot fill shifts at short notice, and the effect on service" beats "staffing".
- If the results cover a related subject, add details that distinguish your subject from it.
- If the results match your subject, read them before changing the text.

## Related Pages

- [Advanced Search](https://oppalerts.com/docs/app/opportunities/advanced_search) How to use the Advanced Search page of the OppAlerts web app.
- [news_search](https://oppalerts.com/docs/mcp/news_search) Search the News Index, a collection of news pages, podcasts, and videos that keeps every document: by semantic similarity (similarity_text), by words over titles and bodies, or both, with date, type, rank, and outbound-link filters.
- [Search Results](https://oppalerts.com/docs/the-data/search-results) What you get back for each page that a News Index or Prospect Index search finds.
- [Duplicates and Copies](https://oppalerts.com/docs/the-data/duplicates-and-copies) See where one story was copied, and find the original reporting behind it.
- [How to Research Industry News](https://oppalerts.com/docs/how-to/research-industry-news) Find the current news, questions, and experts in your industry.
