# Writing a Search

> The four ways a search matches — words, an exact phrase, words with a typo, a pattern — words or meaning, the reranking model, and what each searcher may send

A search has two choices: **how its text matches**, and whether it searches by **words, by
meaning, or both**. This page shows each choice with a real search. Every example ran on
2026-10-12 against an index of a crawl of the Kubernetes documentation (kubernetes.io/docs, about
1,200 pages), with the default of 10 results, and shows the first three. Each searched by words
only unless it says otherwise, with the reranking model's **Fuse** order, which is the default.
Fewer results can change the order, because the reranking model then scores fewer matches.

The text of a search is always literal. No character is an operator, so `--dry-run=server` is
searched for as it is written.

## Four ways to match

| Match | It finds | Example |
| --- | --- | --- |
| **Words** (the default) | The words, in any order and in any form | `roll back a deployment` |
| **Exact** | The words together, in this order, as typed | `kubectl rollout undo` |
| **Fuzzy** | Each word, or the same word with one typo | `kubernets namespase` |
| **Regex** | One word that the pattern matches | `kube-(proxy\|scheduler)` |

On the console, **Find** offers these as **the words**, **the exact phrase**, **the words,
allowing typos** and **a pattern (one term)**. In a request, they are `"match": "words"`,
`"exact"`, `"fuzzy"` and `"regex"`.

### Words

The words in any order and in any form: `deployments` also finds `deployment`. A page that holds
all the words as a phrase ranks higher. A page that holds a code exactly as typed, such as
`kubectl` or `--dry-run`, ranks much higher.

When the text holds two or more words that carry meaning, a page must hold at least two of
them, or one code exactly as typed. Small words such as "a" and "the" do not count.

`roll back a deployment` found:

1. **Performing a Rolling Update** — "To roll back the deployment to your last working version,
   use the rollout undo subcommand…"
2. **Update a Deployment Without Downtime** — "kubectl rollout undo deployment/nginx-deployment"
3. **Deployments** — "…when you roll back to an earlier revision, only the Deployment's Pod
   template part is rolled back."

### Exact

The words together and in this order, in the text of a page. Each word must be as typed: an
exact search does not find other forms of a word. Use it for a command, a product name or an
error message.

`kubectl rollout undo` found the page **kubectl rollout undo**, the kubectl command reference
(titled **GETTING STARTED**), and **Perform a Rollback on a DaemonSet**.

### Fuzzy

Each word, or a word one typo away from it. A typo is one letter added, missing or changed, or
two letters swapped.

Each typo is corrected to the word the index's pages use most that is one typo away, or two for a
word of 7 letters or more. When every word corrects, the search is the corrected words, and it
ranks exactly as they do: `kubernets namespase` finds what `kubernetes namespace` finds, in the
same order, and `deploymnt` puts **Deployments** first, as `deployment` does. A word that corrects
to nothing still finds a word one typo away from it or from its root.

### Regex

The text is a pattern that must match **one whole word** of the page. Upper and lower case match
the same. A word here can be a code such as `kube-proxy` or `snake_case`, or a part of it, such as
`kube`.

`kube-(proxy|scheduler)` found **Good practices for Dynamic Resource Allocation as a Cluster
Admin**, **Installing Addons** and **Cluster Architecture**. `kube-.*` finds every word that
starts with `kube-`.

A pattern cannot hold a space, because it matches one word. Begin a pattern with a few fixed
letters: a pattern that could match too many words is refused, in these words:

> `query.text` is too broad a pattern to search: start it with a few fixed letters and use fewer
> wildcards, as `deploy.*` rather than `.*a.{20}`

A pattern the search cannot read is refused too, with the place it stopped: `kube-(proxy` gets
"error: unclosed group". A visitor reads the same advice without the field name, and "This is not
a pattern the search can read. Check its brackets and backslashes, or search by words." for a
pattern the search cannot read.

## Words, meaning, or both

Each search can read the **words** of a page, its **meaning**, or **both**. On the console this
is **By**: **Words only**, **Meaning only** or **Both**. In a request it is `"mode"`: `"text"`,
`"semantic"` or `"hybrid"`, the default.

- **Words** finds the text as the match above says. It finds an exact name, such as a
  command-line flag, that meaning can miss.
- **Meaning** finds a passage that says the same thing in other words. It needs words that
  carry meaning, so it does not run for a pattern alone. It runs only on an index with **Search
  by meaning as well as by words** on.
- **Both** runs the two at once and ranks their results together. This is how a loop's own
  searches run.

`how do I go back to the version that worked`, by meaning only, found the kubectl command
reference (**GETTING STARTED**), **StatefulSets** and **Update a Deployment Without Downtime**.
The third is at the passage "If a new version introduces issues, you can roll back to a previous
revision.", which shares almost no words with the search.

A search by meaning also embeds its text once, at the index's embedding price. See
[What an index costs](/docs/search/overview.md#what-an-index-costs).

## The reranking model

After the words and the meaning find their matches, a **reranking model** can score each match
against the search, put the best first, and hide the matches it scores too weak. Your account
chooses this for each kind of searcher under **Settings > Search order**; see
[How results are ordered](/docs/search/overview.md#how-results-are-ordered).

What the answer says about it:

- When it hides matches, the answer says how many, for example "3 matches were too weak to
  show".
- When it would hide every match, it hides none: the answer is the plain order, and says
  "Showing the closest matches by words and meaning."
- It never hides a match that holds the text exactly as typed, such as `WT-30`.
- It does not run for a pattern, because a pattern holds no words to score by. The answer then
  says "the query holds no natural-language text to score the results by; the results are in
  the plain order".

By fuzzy match, the reranking model scores the corrected words, so a typo that corrects is
scored as the word it corrects to, and `deploymnt` is ordered as `deployment` is. A typo that
corrects to nothing is scored as typed, and the model can score good matches too weak because of
it. Fix
the typo, or send `"rerank": false` where the request takes it.

## What each searcher may send

| Searcher | Ways to match | Words or meaning | Reranking model | Results |
| --- | --- | --- | --- | --- |
| You, on **Indexes** | All four | Your choice | Your account's setting for **Your search** | Up to 10 |
| A loop's agent | All four, and more (below) | Its choice | Your account's setting for **A run's agent** | 1 to 50 |
| A visitor, in the embed's search box | All four, as **Match** | Both | Your account's setting for **Your visitors** | Up to 10 |
| A visitor or your server, through a loop's search API | All four | `mode` | `rerank`, or your setting for **Your visitors** | 1 to 20 |
| Your server, with a search key | Words | `mode` | `rerank`, or your setting for **Your search keys** | 1 to 20 |

A page you build with the React SDK's `useSearch` hook may send all four; its `SearchBox` shows
them as **Match**, and `matches` offers fewer.
The requests, the answers and the refusals of the two APIs are on [Search API](/docs/api/search.md).

A loop's agent writes its own searches, and it may also:

- join searches with `all` (each must match), `any` (one must match) and `not` (must not match);
- search one part of a page: its `title`, `heading`, `body` or `url`;
- give separate text for the meaning half, with `semantic`.

You do not write these. To steer what a loop searches, say in its instructions which index holds
what; see [Letting a Loop Search](/docs/guide/search-indexes.md).
