> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/working-with-data/search-by-text.md).

# Search by text

Query a Telys collection with a plain string using search\_text(), which embeds your query with the collection's embedder and returns the nearest records.

`search_text` is the text query path: pass a string, Telys embeds it with the collection's embedder and runs the same nearest-neighbor search as [`search`](https://docs.telys.ai/working-with-data/search-by-vector.md). It is the counterpart to `add_texts` — if you added text, you search text.

## Signature

```python
Collection.search_text(
    text,
    top_k=10,
    where=None,
    explain=False,
    target_recall=None,
    with_metadata=False,
    mode="dense",
) -> dict
```

| Parameter       | Type                 | Default   | Meaning                                                                                                                                                                                                                            |
| --------------- | -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`          | `str`                | —         | The query string. Embedded with the collection's embedder (via `embed_queries`).                                                                                                                                                   |
| `top_k`         | `int`                | `10`      | Maximum number of results to return.                                                                                                                                                                                               |
| `where`         | `Eq \| dict \| None` | `None`    | Restrict to a partition/filter column (see [Filter results](https://docs.telys.ai/working-with-data/filter-results.md)).                                                                                                           |
| `explain`       | `bool`               | `False`   | Add an `"explain"` trace describing how the query ran.                                                                                                                                                                             |
| `target_recall` | `float \| None`      | `None`    | Per-query recall/latency hint for the planner (e.g. `0.95`).                                                                                                                                                                       |
| `with_metadata` | `bool`               | `False`   | Add a `"metadata"` list aligned with the returned ids.                                                                                                                                                                             |
| `mode`          | `str`                | `"dense"` | `"dense"` embeds + vector-searches; `"lexical"` runs on-device BM25 over code tokens (no embedding). Lexical needs `lexical=True` at creation + [`build_lexical`](https://docs.telys.ai/working-with-data/build-lexical-index.md). |

Like `search`, the result is `{"ids": [...], "scores": [...]}`, plus `"explain"` and `"metadata"` when requested. `ids` are ordered best-match first.

{% hint style="warning" %}
`search_text` needs an embedder; on a collection created with `embedder=None` it raises `RuntimeError`. Attach one at [creation](https://docs.telys.ai/working-with-data/create-a-collection.md) or reopen with `telys.open_collection(name, embedder=...)` so query and stored documents share one vector space.
{% endhint %}

## Basic query

```python
from telys import Telys
from telys.embedding import AlgentaMultigramEmbedder

telys = Telys("telys-store")
# "memories" was created with filter_columns=("scope", "topic"), so both keys
# come back in each hit's metadata under with_metadata=True.
memories = telys.open_collection("memories", embedder=AlgentaMultigramEmbedder())

result = memories.search_text("how do cells produce energy?", top_k=5, with_metadata=True)
```

```python
{
    "ids": ["bio-1", "bio-2", "bio-3"],
    "scores": [0.78, 0.66, 0.31],
    "metadata": [
        {"scope": "user:42", "topic": "biology"},
        {"scope": "user:42", "topic": "biology"},
        {"scope": "user:42", "topic": "biology"},
    ],
}
```

## Filter and tune per query

```python
from telys import Eq

result = memories.search_text(
    "energy",
    top_k=5,
    where=Eq("scope", "user:42"),
    target_recall=0.95,
    explain=True,
)
result["explain"]        # trace of how the query was executed
```

## Expected result

You pass a string and get parallel `ids` and `scores`, best-match first, plus an aligned `metadata` list with `with_metadata=True`. No manual embedding step is involved:

```python
>>> res = memories.search_text("mitochondria", top_k=2, with_metadata=True)
>>> res["ids"]
['bio-1', 'bio-2']
>>> res["scores"][0] >= res["scores"][1]
True
>>> res["metadata"][0]
{'scope': 'user:42', 'topic': 'biology'}
```

## Lexical (BM25) text search

With `mode="lexical"`, `search_text` skips embedding and runs an on-device BM25 index over your code tokens — keyword/code recall with no model. It needs a collection created with `lexical=True` and a [`build_lexical()`](https://docs.telys.ai/working-with-data/build-lexical-index.md) pass:

```python
from telys import Eq

hits = col.search_text(
    "reconcile ledger entries",
    top_k=5,
    where=Eq("scope_key", "acme/payments"),   # BM25 over just this partition
    mode="lexical",
)
```

Same `{"ids": [...], "scores": [...]}` shape; rank by position (BM25 scores are not comparable to cosine). See [Build a lexical index](https://docs.telys.ai/working-with-data/build-lexical-index.md) for the full workflow.

## Next steps

* [Build a lexical index](https://docs.telys.ai/working-with-data/build-lexical-index.md) — enable `mode="lexical"` with `lexical=True` + `build_lexical`.
* [Filter results](https://docs.telys.ai/working-with-data/filter-results.md) — narrow a text search with `Eq` or a single-key dict.
* [Search by vector](https://docs.telys.ai/working-with-data/search-by-vector.md) — the raw-vector query path when you embed the query yourself.
* [Lexical vs dense embeddings](https://docs.telys.ai/understand-telys/lexical-vs-dense.md) — what "text match" means for the lexical embedders.
