---
question: Do I pass query text or a vector to search_similar?
kind: task
via_web: na
via_cli: na
via_python: available
via_api: na
via_config: na
ref_python: search_similar
prereq: The collection holds vectors made with the embedding model you will query with. See [Add embeddings](/user-guide/build/vector-search/add-embeddings).
next:
  - /capabilities/build/vector-search/add-embeddings
  - /capabilities/build/agents/give-it-tools
---

# Search

`search_similar` returns the stored vectors nearest to a query vector. It takes a vector, not text: embed the question with the same model that embedded the documents.

## Web UI

Not applicable. Nexus has no similarity search screen. System › Data › Vector store browses collections and vectors by id only. To search from chat, give an agent a tool that calls the Python steps: see [Give it tools](/user-guide/build/agents/give-it-tools).

## CLI

Not applicable. There is no `abi` command for the vector store. Use the Python steps on this page.

## Python

### Embed the question

```python
import numpy as np

embedding = self.engine.services.model_registry.get_default_embedding_model().model
query = np.array(embedding.embed_query("the question"))
```

### Search

```python
store = self.engine.services.vector_store
hits = store.search_similar(
    "my_module_notes",
    query,
    k=5,
    filter={"source": "manual"},
)
for hit in hits:
    print(hit.id, hit.score, hit.payload)
```

`k` defaults to 10 and must be above 0. `filter` matches metadata keys by equality. `include_vectors=True` returns each stored vector; `include_metadata` is on by default. Each hit is a `SearchResult` with `id`, `score`, `vector`, `metadata` and `payload`.

:::warning Score direction
On `qdrant` and `qdrant_in_memory`, `score` is a similarity: higher is closer. On `sqlite_vec`, the `abi dev up` default, `score` is the distance: lower is closer. `score_threshold` keeps hits with `score >= threshold` on every backend, so on `sqlite_vec` it keeps the farther hits.
:::

### Read entries by id

```python
doc = store.get_document("my_module_notes", doc_id)  # VectorDocument, or None

cursor = None
while True:
    page = store.list_documents("my_module_notes", limit=100, cursor=cursor)
    for entry in page.documents:
        ...
    if page.next_cursor is None:
        break
    cursor = page.next_cursor
```

`limit` is 1 to 10,000.

## REST API

Not applicable. Neither the engine API nor the Nexus API has a similarity search route. The System routes read entries by id only: see [Add embeddings](/user-guide/build/vector-search/add-embeddings?via=api).

## Config

Not applicable. Search is a call, not a setting.