# RAG.SEARCH

> Search a RAG pipeline by query text and embedding, with optional metadata filters.

URL: https://docs.hotkv.com/commands/rag-search/

```
RAG.SEARCH pipeline query_text [K n] [ALPHA weight] [VECTOR vector] [FILTER key value [key value ...]]
```

- Group: RAG
- Complexity: O(N) where N is the number of chunks
- HotKV Cloud: Performance and Scale plans
- On-Premise: requires the rag-pipeline license feature

A RAG pipeline splits your documents into chunks, keeps each chunk with the embedding you computed for it, and answers searches that combine keyword (BM25) relevance with vector similarity, all inside HotKV. `RAG.SEARCH` scores chunks by keyword relevance to `query_text`
and, when you pass `VECTOR`, by similarity to the query embedding, then
returns the best `K` chunks ranked by the combined score.

## Options

| Option | Effect |
| --- | --- |
| `K n` | Number of results. Must be positive. Default `5`. |
| `ALPHA weight` | How much the vector score counts against the keyword score, from `0.0` (keywords only) to `1.0` (vectors only). Default `0.5`. |
| `VECTOR vector` | The query embedding as one argument of comma-separated numbers, with the pipeline's dimensions. |
| `FILTER key value ...` | Only chunks whose metadata has every given key with exactly the given value. |

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Always | Array of results, best first. Empty for an unknown pipeline or no matches. | Same |

Each result is an array of bulk strings: the chunk id, the document id, the
chunk text, the combined score, the vector score, the keyword (BM25) score,
followed by the chunk's metadata as alternating keys and values. Scores are
decimal strings with six digits after the point; higher is better.

Errors:

- `ERR invalid K` if `K` is not a positive integer.
- `ERR invalid ALPHA (must be 0.0 to 1.0)` if `ALPHA` is out of range or not a number.
- `ERR expected N dimensions, got M` if `VECTOR` has the wrong number of values.
- `ERR wrong number of arguments for 'rag.search' command` if the argument count is wrong.
- `NOLICENSE rag-pipeline requires a HotKV license. Contact sales@hotkv.com` if your license does not include the `rag-pipeline` feature.

## Examples

```
127.0.0.1:6379> RAG.SEARCH faq "how do I reset my password" K 2 VECTOR 0.88,0.12,0.01
1) 1) "doc:1:0"
   2) "doc:1"
   3) "To reset your password, click Forgot password on the login screen."
   4) "1.000000"
   5) "0.999700"
   6) "1.386294"
   7) "source"
   8) "help-center"
2) 1) "doc:1:1"
   2) "doc:1"
   3) "Billing questions go to the billing team."
   4) "0.255100"
   5) "0.510250"
   6) "0.000000"
   7) "source"
   8) "help-center"
```

The score values depend on your documents and embeddings.

## Compatibility

HotKV-only command. Redis and Valkey have no equivalent.

## See also

[RAG.CREATE](https://docs.hotkv.com/commands/rag-create/index.md), [RAG.INGEST](https://docs.hotkv.com/commands/rag-ingest/index.md), [RAG.STATS](https://docs.hotkv.com/commands/rag-stats/index.md), [RAG.DROP](https://docs.hotkv.com/commands/rag-drop/index.md), [RAG.LIST](https://docs.hotkv.com/commands/rag-list/index.md), [RERANK.GET](https://docs.hotkv.com/commands/rerank-get/index.md), [AI features guide](https://docs.hotkv.com/ai-features/index.md)