> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# $ann

> Find the documents whose HYBRID field is closest in meaning to a text.

The `$ann` retriever runs a semantic search. It finds the documents whose `HYBRID` field is closest in
meaning to the query text, even when they use different words.

`$ann` works only on [`HYBRID` fields](https://upstash.com/docs/redis/search/schema-definition#hybrid-fields).

```json theme={"system"}
{ "$ann": { "field": "description", "query": "something to block noise on a flight" } }
```

### Parameters

| Parameter | Description | Default |
| - | - | - |
| `field` | Required. The `HYBRID` field to search. | |
| `query` | Required. The text to search for. Cannot be empty. | |
| `profile` | Accuracy and speed trade-off: `fast`, `balanced`, or `precise`. | `balanced` |
| `filter` | A query object. Only documents that match it are returned. | No filter |
| `weight` | A number, `0` or greater. It scales how much the results add to the `$rrf` score. Valid only inside [`$rrf`](./rrf). | `1` |

### Results

Results are ordered by similarity. Scores are between `0` and `1`, and a higher score means a closer
match.

`$ann` has no score threshold. It returns up to `LIMIT` documents, even when they are not similar to
the query.

The search is approximate. `profile` trades speed for accuracy, the same way as `PROFILE` in
[`VECTOR.QUERY`](https://upstash.com/docs/redis/commands/vector/vector-query). Paging with `OFFSET` is also approximate, so two
pages of the same query can overlap or miss a document.

### Filtering

Use `filter` to search within a subset of documents. The filter is a regular query object, so all
[query operators](https://upstash.com/docs/redis/search/query-operators/boolean-operators/overview) work in it. The filter
selects the documents, but it does not change their scores.

### Indexing

Search updates the embeddings before the full-text index. Right after a write, `$ann` can return a
document that full-text queries do not find yet.
[`SEARCH.WAITINDEXING`](https://upstash.com/docs/redis/commands/search/search-waitindexing) waits for both.

### Examples

> [tab] TypeScript
>
> ```ts theme={"system"}
> // Search by meaning
> await index.query({
>   filter: { $ann: { field: "description", query: "something to block noise on a flight" } },
> });
>
> // Search by meaning within cheap sports products
> await index.query({
>   filter: {
>     $ann: {
>       field: "description",
>       query: "headphones for running",
>       filter: { category: "sports", price: { $lt: 100 } },
>     },
>   },
> });
>
> // Use the most accurate profile, and return keys and scores only
> await index.query({
>   filter: { $ann: { field: "description", query: "headphones for running", profile: "precise" } },
>   select: {},
> });
> ```

> [tab] Python
>
> ```python theme={"system"}
> # Search by meaning
> index.query(
>     filter={"$ann": {"field": "description", "query": "something to block noise on a flight"}}
> )
>
> # Search by meaning within cheap sports products
> index.query(
>     filter={
>         "$ann": {
>             "field": "description",
>             "query": "headphones for running",
>             "filter": {"category": "sports", "price": {"$lt": 100}},
>         }
>     }
> )
>
> # Use the most accurate profile, and return keys and scores only
> index.query(
>     filter={
>         "$ann": {
>             "field": "description",
>             "query": "headphones for running",
>             "profile": "precise",
>         }
>     },
>     select={},
> )
> ```

> [tab] Redis CLI
>
> ```bash theme={"system"}
> # Search by meaning
> SEARCH.QUERY products '{"$ann": {"field": "description", "query": "something to block noise on a flight"}}'
>
> # Search by meaning within cheap sports products
> SEARCH.QUERY products '{"$ann": {"field": "description", "query": "headphones for running", "filter": {"category": "sports", "price": {"$lt": 100}}}}'
>
> # Use the most accurate profile, and return keys and scores only
> SEARCH.QUERY products '{"$ann": {"field": "description", "query": "headphones for running", "profile": "precise"}}' NOCONTENT
> ```

See [Query Options](./overview#query-options) for the `SEARCH.QUERY` options that `$ann` does not
support.


## Related topics

- [Hybrid Search](https://upstash.com/docs/redis/search/hybrid-search.md)
- [$rrf](https://upstash.com/docs/redis/search/retrievers/rrf.md)
- [Overview](https://upstash.com/docs/redis/search/retrievers/overview.md)
- [SEARCH.COUNT](https://upstash.com/docs/redis/commands/search/search-count.md)
- [SEARCH.AGGREGATE](https://upstash.com/docs/redis/commands/search/search-aggregate.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.