# Searching

Text search with rg and grep, meaning search with similar, and reordering a bounded set with rerank.

`rg` and `grep` keep records whose text matches a pattern. `similar` finds the nearest records by vector. `rerank` reorders a bounded set by a second vector score.

## By text

- `rg`: Keep whole records in order when their compact JSON or named field matches the pattern. Arguments: field: optional top-level field with a leading dot; pattern: a regular expression in double quotes; flags: optional quoted -i, -s, -S, -w, -x, -F, -v and -U switches and their long forms; --no-ignore-case resets case sensitivity; -U dot matches newlines.
- `grep`: Alias of rg: keep whole records in order when their compact JSON or named field matches the pattern. Arguments: field: optional top-level field with a leading dot; pattern: a regular expression in double quotes; flags: optional quoted -i, -s, -S, -w, -x, -F, -v and -U switches and their long forms; --no-ignore-case resets case sensitivity; -U dot matches newlines.


The third argument of `rg` and `grep` is a quoted string of switches.

- `-i` (--ignore-case): Match regardless of case. --no-ignore-case resets it.
- `-s` (--case-sensitive): Match case exactly.
- `-S` (--smart-case): Case-insensitive unless the pattern has an upper-case letter.
- `-w` (--word-regexp): Match whole words only.
- `-x` (--line-regexp): Match the whole value only.
- `-F` (--fixed-strings): Treat the pattern as literal text, not a regular expression.
- `-v` (--invert-match): Keep records that do not match.
- `-U` (--multiline): Let a dot match a newline.


## By meaning

`similar` and `rerank` read a declared vector field. The question is either quoted text, which the service embeds, or `record("id")`, which uses that record's stored vector.

The record form needs a vector stored on that field. The text form needs the complete embedding configuration, a declared embedded field and its matching model ready in the worker. A supplied-vector field alone cannot embed a text question. Missing settings are `embed_not_configured`; a missing source record or field has its own named refusal. The notes examples assume a notes collection and those embedding prerequisites. They are not steps that the first-records example has already performed.

- `similar`: Search by vector similarity first after its source or later over the records that reached it. Arguments: field: a top-level vector field with a leading dot; question: double-quoted text or record("id"); measure: cosine, l2 or dot.
- `record`: Use the stored vector of the named record as the similarity question. Arguments: id: a record id in double quotes.
- `rerank`: Drain the bounded upstream, reorder by vector score, replace scores and count unscored records last; no continuation. Arguments: field: a top-level vector field with a leading dot; question: double-quoted text or record("id"); measure: cosine, l2 or dot.


- `cosine`: Compare vectors by their cosine similarity.
- `l2`: Compare vectors by their Euclidean distance.
- `dot`: Compare vectors by their dot product.


> Text is never cut
> Text given to `similar` is embedded whole. Text longer than the model's window is refused by name rather than trimmed, so a search never runs on half a sentence.