> 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-vector.md).

# Search by vector

Query a Telys collection with a precomputed query vector using search(), and read back ids, scores, optional metadata, and an explain trace.

`search` is the raw-vector query path: pass a query vector of exactly `dim` values and Telys returns the nearest records. Use it when you already have query embeddings, or on a vectors-only collection. To query with a string, see [Search by text](https://docs.telys.ai/working-with-data/search-by-text.md).

## Signature

```python
Collection.search(
    vector,
    top_k=10,
    where=None,
    explain=False,
    target_recall=None,
    with_metadata=False,
) -> dict
```

| Parameter       | Type                         | Default | Meaning                                                                                                                  |
| --------------- | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ |
| `vector`        | 1-D `float32` (length `dim`) | —       | The query vector. Its length must equal the collection's `dim`.                                                          |
| `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.                                                                   |

The result is always `{"ids": [...], "scores": [...]}`, plus `"explain"` when `explain=True` and `"metadata"` when `with_metadata=True`. `ids` are ordered best-match first; `scores[i]` matches `ids[i]`.

## Basic query

```python
import numpy as np
from telys import Telys

memories_dim = 64                                # length of every stored & query vector

telys = Telys("telys-store")
memories = telys.create_collection(
    "memories",
    dim=memories_dim,
    partition_by="scope",
    # Only declared filter_columns round-trip through with_metadata=True; list
    # "scope" too so the partition key comes back in each hit's metadata.
    filter_columns=("scope", "topic"),
)
memories.add(
    np.random.rand(5, memories_dim).astype("float32"),
    ids=["bio-1", "bio-2", "bio-3", "v-1", "v-2"],
    metadata=[
        {"scope": "user:42", "topic": "biology"},
        {"scope": "user:42", "topic": "biology"},
        {"scope": "user:42", "topic": "biology"},
        {"scope": "user:42", "topic": "vectors"},
        {"scope": "user:42", "topic": "vectors"},
    ],
)

query = np.random.rand(memories_dim).astype("float32")   # length == dim
result = memories.search(query, top_k=5)
```

```python
{
    "ids": ["bio-2", "bio-1", "v-1", "v-2", "bio-3"],
    "scores": [0.83, 0.71, 0.44, 0.41, 0.39],
}
```

## Return metadata and an explain trace

```python
result = memories.search(query, top_k=5, with_metadata=True, explain=True)

result["ids"]           # ['bio-2', 'bio-1', ...]
result["scores"]        # [0.83, 0.71, ...]
result["metadata"]      # [{'scope': 'user:42', 'topic': 'biology'}, ...] aligned with ids
result["explain"]       # trace of how the query was executed
```

## Filter and tune per query

Use `where` to constrain to a partition or filter column, and `target_recall` to nudge the recall/latency tradeoff:

```python
from telys import Eq

result = memories.search(
    query,
    top_k=5,
    where=Eq("scope", "user:42"),
    target_recall=0.95,
)
```

{% hint style="warning" %}
The query vector length must equal the collection's `dim`; `search` validates this and raises on a mismatch. Embed the query with the *same* model used for the stored vectors. See [Embedding dimension mismatches](https://docs.telys.ai/troubleshooting/dimension-mismatches.md).
{% endhint %}

## Expected result

`ids` and `scores` are parallel lists ordered best-match first. `with_metadata=True` adds a `metadata` list in the same order, so `result["ids"][0]` and `result["metadata"][0]` describe the same record:

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

## Next steps

* [Search by text](https://docs.telys.ai/working-with-data/search-by-text.md) — let Telys embed a string query for you.
* [Filter results](https://docs.telys.ai/working-with-data/filter-results.md) — scope a search with `Eq` or a single-key dict.
* [Search internals (IVF)](https://docs.telys.ai/understand-telys/search-internals-ivf.md) — what `target_recall` actually controls.
