> For the complete documentation index, see [llms.txt](https://docs.hyper-space.io/hyperspace-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyper-space.io/hyperspace-docs/~/changes/uCQNjcW7J3OXknfYJaVa/api-documentation/score-function/distance.md).

# distance

The function  distance`(str vector_fieldname1, str vector_fieldname2, r32 min_score)` calculates **vector distance (KNN) between document fields**, according to the distance metric defined in the data schema config file. 

if the distance score is below <mark style="color:purple;">min\_score</mark>, the function will return **0**. Otherwise, it will return **the KNN\_score**.

Any arithmetic combination (+, \*, \*, /) of `distance()`and a variable or a constant is allowed.

`min_score` can be a dynamic value, included in the query parameters.

### Input

* <mark style="color:purple;">vector\_fieldname1</mark> (str) - the name of the query field to use in the KNN calculation. params\[fieldname1] must be of type **dense\_vector**.
* <mark style="color:purple;">vector\_fieldname2</mark> (str, default=fieldname1) - the name of the document field to use in the KNN calculation. params\[fieldname1] must be of type **dense\_vector**. \
  By default <mark style="color:purple;">vector\_fieldname2</mark> is set to <mark style="color:purple;">vector\_fieldname1</mark>.&#x20;
* <mark style="color:purple;">min\_score</mark> (float, default=0) - the score threshold. If the distance score is below this value, distance() will return 0.

### Output

* <mark style="color:purple;">(int)</mark> - The returned values will be the KNN distance between <mark style="color:purple;">vector\_fieldname1</mark> to <mark style="color:purple;">vector\_fieldname2</mark> if it is greater the <mark style="color:purple;">min\_thershold</mark>, and 0 otherwise.

### Limitations

* <mark style="color:purple;">params</mark>\[<mark style="color:purple;">vector\_fieldname2]</mark> and <mark style="color:purple;">doc\[vector\_fieldname2]</mark> must be indexed using the same metric.
* The distance function can only be used as part of a return statement. In addition, all other `return` statements must only `return 0`, `False` or none. \
  For example, only return statements of the following types are allowed:

```python
def score_function(params, doc):
    if match("genre"):
        return
    else if match("countries"):
        return False
    score = rarity_max("tags")        
    if score < 1:
        return 0
    return score  * knn_filter("tagline_embedding", "overview_embedding")
```

{% hint style="info" %}
The distance() function is used as part of Hybrid Search Score functions. It allows to you to combine the KNN score with the lexical score function
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hyper-space.io/hyperspace-docs/~/changes/uCQNjcW7J3OXknfYJaVa/api-documentation/score-function/distance.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.