Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Score boosting #1506

Draft
wants to merge 5 commits into
base: master
Choose a base branch
from
Draft

Docs: Score boosting #1506

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3a05046
Add score boosting section to hybrid queries
coszio Mar 10, 2025
ac8023f
add decay formulas docs
coszio Mar 13, 2025
9eecf6c
Add datetime function to formula operators and update limitations
coszio Mar 21, 2025
d526745
add datetime_key expression
coszio Mar 26, 2025
c5659e8
use the name of the decay function in interface for the table
coszio Mar 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
335 changes: 109 additions & 226 deletions qdrant-landing/content/documentation/concepts/hybrid-queries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1025,259 +1025,142 @@ collection `another_collection`.
The fetched vector(s) must match the characteristics of the <code>using</code> vector, otherwise, an error will be returned.
</aside>

## Score boosting

## Re-ranking with payload values
_Available as of v1.14.0_

The Query API can retrieve points not only by vector similarity but also by the content of the payload.
When introducing vector search to specific applications, sometimes business logic needs to be considered for ranking the final list of results.

There are two ways to make use of the payload in the query:
A quick example is [our own documentation search bar](https://github.com/qdrant/page-search).
It has vectors for every part of the documentation site. If one were to perform a search by "just" using the vectors, all kinds of elements would be equally considered good results.
However, when searching for documentation, we can establish a hierarchy of importance:

* Apply filters to the payload fields, to only get the points that match the filter.
* Order the results by the payload field.
`title > content > snippets`

Let's see an example of when this might be useful:
One way to solve this is to weight the results based on the kind of element.
For example, we can assign a higher weight to titles and content, and keep snippets unboosted.

Pseudocode would be something like:

`score = score + (is_title * 0.5) + (is_content * 0.25)`

Query API can rescore points with custom formulas. They can be based on:
- Dynamic payload values
- Conditions
- Scores of prefetches

To express the formula, the syntax uses objects to identify each element.
Taking the documentation example, the request would look like this:

```http
POST /collections/{collection_name}/points/query
{
"prefetch": [
{
"query": [0.01, 0.45, 0.67, ...], // <-- dense vector
"filter": {
"must": {
"key": "color",
"match": {
"value": "red"
}
}
},
"limit": 10
},
{
"query": [0.01, 0.45, 0.67, ...], // <-- dense vector
"filter": {
"must": {
"key": "color",
"match": {
"value": "green"
}
}
},
"limit": 10
"prefetch": {
"query": [0.2, 0.8, ...], // <-- dense vector
"limit": 50
}
"query": {
"formula": {
"sum": [
"$score,
{ "mult": [ 0.5, { "key": "tag", "match": { "any": ["h1", "h2", "h3", "h4"] } } ] },
{ "mult": [ 0.25, { "key": "tag", "match": { "any": ["p", "li"] } } ] }
]
}
],
"query": { "order_by": "price" }
}
}
```

```python
from qdrant_client import QdrantClient, models

client = QdrantClient(url="http://localhost:6333")

client.query_points(
collection_name="{collection_name}",
prefetch=[
models.Prefetch(
query=[0.01, 0.45, 0.67], # <-- dense vector
filter=models.Filter(
must=models.FieldCondition(
key="color",
match=models.MatchValue(value="red"),
),
),
limit=10,
),
models.Prefetch(
query=[0.01, 0.45, 0.67], # <-- dense vector
filter=models.Filter(
must=models.FieldCondition(
key="color",
match=models.MatchValue(value="green"),
),
),
limit=10,
),
],
query=models.OrderByQuery(order_by="price"),
)
```

```typescript
import { QdrantClient } from "@qdrant/js-client-rest";

const client = new QdrantClient({ host: "localhost", port: 6333 });

client.query("{collection_name}", {
prefetch: [
{
query: [0.01, 0.45, 0.67], // <-- dense vector
filter: {
must: {
key: 'color',
match: {
value: 'red',
},
}
},
limit: 10,
},
{
query: [0.01, 0.45, 0.67], // <-- dense vector
filter: {
must: {
key: 'color',
match: {
value: 'green',
},
}
},
limit: 10,
},
],
query: {
order_by: 'price',
},
});
```

```rust
use qdrant_client::Qdrant;
use qdrant_client::qdrant::{Condition, Filter, PrefetchQueryBuilder, Query, QueryPointsBuilder};

let client = Qdrant::from_url("http://localhost:6334").build()?;

client.query(
QueryPointsBuilder::new("{collection_name}")
.add_prefetch(PrefetchQueryBuilder::default()
.query(Query::new_nearest(vec![0.01, 0.45, 0.67]))
.filter(Filter::must([Condition::matches(
"color",
"red".to_string(),
)]))
.limit(10u64)
)
.add_prefetch(PrefetchQueryBuilder::default()
.query(Query::new_nearest(vec![0.01, 0.45, 0.67]))
.filter(Filter::must([Condition::matches(
"color",
"green".to_string(),
)]))
.limit(10u64)
)
.query(Query::new_order_by("price"))
).await?;
```
TODO: add all clients

There are multiple expressions available, check the [API docs for specific details](https://api.qdrant.tech/v-1-13-x/api-reference/search/query-points#request.body.query.Query%20Interface.Query.Formula%20Query.formula).
- **constant** - A floating point number. e.g. `0.5`.
- `"$score"` - Reference to the score of the point in the prefetch. This is the same as `"$score[0]"`.
- `"$score[0]"`, `"$score[1]"`, `"$score[2]"`, ... - When using multiple prefetches, you can reference specific prefetch with the index within the array of prefetches.
- **payload key** - Any plain string will refer to a payload key. This uses the jsonpath format used in every other place, e.g. `key` or `key.subkey`. It will try to extract a number from the given key.
- **condition** - A filtering condition. If the condition is met, it becomes `1.0`, otherwise `0.0`.
- **mult** - Multiply an array of expressions.
- **sum** - Sum an array of expressions.
- **div** - Divide an expression by another expression.
- **abs** - Absolute value of an expression.
- **pow** - Raise an expression to the power of another expression.
- **sqrt** - Square root of an expression.
- **log10** - Base 10 logarithm of an expression.
- **ln** - Natural logarithm of an expression.
- **exp** - Exponential function of an expression (`e^x`).
- **geo distance** - Haversine distance between two geographic points. Values need to be `{ "lat": 0.0, "lon": 0.0 }` objects.
- **decay** - Apply a decay function to an expression, which clamps the output between 0 and 1. Available decay functions are **linear**, **exponential**, and **gaussian**. [See more](#boost-points-closer-to-user).
- **datetime** - Parse a datetime string (see formats [here](/documentation/concepts/payload/#datetime)), and use it as a POSIX timestamp, in seconds.

It is possible to define a default for when the variable (either from payload or prefetch score) is not found. This is given in the form of a mapping from variable to value.
If there is no variable, and no defined default, a default value of `0.0` is used.

```java
import static io.qdrant.client.ConditionFactory.matchKeyword;
import static io.qdrant.client.QueryFactory.nearest;
import static io.qdrant.client.QueryFactory.orderBy;
<aside role="status">

**Considerations when using formula queries:**

- Formula queries can only be used as a rescoring step.
- Formula results are always sorted in descending order (bigger is better). **For euclidean scores, make sure to negate them** to sort closest to farthest.
- If a score or variable is not available, and there is no default value, it will return an error.
- If a value is not a number (or the expected type), it will return an error.
- To leverage payload indices, single-value arrays are considered the same as the inner value. For example: `[0.2]` is the same as `0.2`, but `[0.2, 0.7]` will be interpreted as `[0.2, 0.7]`
- Multiplication and division are lazily evaluated, meaning that if a 0 is encountered, the rest of operations don't execute (e.g. `0.0 * condition` won't check the condition).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does it make sense to add a note about performance?

  • use indexed payload values
  • less payload usage in formulas means more performant formulas
  • more performant formulas means faster search

</aside>

import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;
import io.qdrant.client.grpc.Points.Filter;
import io.qdrant.client.grpc.Points.PrefetchQuery;
import io.qdrant.client.grpc.Points.QueryPoints;
### Boost points closer to user
Another example. Combine the score with how close the result is to a user.

QdrantClient client =
new QdrantClient(QdrantGrpcClient.newBuilder("localhost", 6334, false).build());
Considering each point has an associated geo location, we can calculate the distance between the point and the request's location.

client
.queryAsync(
QueryPoints.newBuilder()
.setCollectionName("{collection_name}")
.addPrefetch(
PrefetchQuery.newBuilder()
.setQuery(nearest(0.01f, 0.45f, 0.67f))
.setFilter(
Filter.newBuilder().addMust(matchKeyword("color", "red")).build())
.setLimit(10)
.build())
.addPrefetch(
PrefetchQuery.newBuilder()
.setQuery(nearest(0.01f, 0.45f, 0.67f))
.setFilter(
Filter.newBuilder().addMust(matchKeyword("color", "green")).build())
.setLimit(10)
.build())
.setQuery(orderBy("price"))
.build())
.get();
```
Assuming we have cosine scores in the prefetch, we can use a helper function to clamp the geographical distance between 0 and 1, by using a decay function. Once clamped, we can sum the score and the distance together. Pseudocode:

```csharp
using Qdrant.Client;
using Qdrant.Client.Grpc;
using static Qdrant.Client.Grpc.Conditions;
`score = score + gauss_decay(distance)`

var client = new QdrantClient("localhost", 6334);
In this case we use a **gauss_decay** function.

await client.QueryAsync(
collectionName: "{collection_name}",
prefetch: new List <PrefetchQuery> {
new() {
Query = new float[] {
0.01f, 0.45f, 0.67f
},
Filter = MatchKeyword("color", "red"),
Limit = 10
},
new() {
Query = new float[] {
0.01f, 0.45f, 0.67f
```http
POST /collections/{collection_name}/points/query
{
"prefetch": { "query": [0.2, 0.8, ...], "limit": 50 },
"query": {
"formula": {
"sum": [
"$score",
{
"gauss_decay": {
"scale": 5000, // 5km
"x": {
"geo_distance": {
"origin": { "lat": 52.504043, "lon": 13.393236 } // Berlin
"to": "geo.location"
}
}
}
}
]
},
Filter = MatchKeyword("color", "green"),
Limit = 10
"defaults": { "geo.location": {"lat": 48.137154, "lon": 11.576124} } // Munich
}
},
query: (OrderBy) "price",
limit: 10
);
}
```

```go
import (
"context"

"github.com/qdrant/go-client/qdrant"
)

client, err := qdrant.NewClient(&qdrant.Config{
Host: "localhost",
Port: 6334,
})
For all decay functions, there are these parameters available

client.Query(context.Background(), &qdrant.QueryPoints{
CollectionName: "{collection_name}",
Prefetch: []*qdrant.PrefetchQuery{
{
Query: qdrant.NewQuery(0.01, 0.45, 0.67),
Filter: &qdrant.Filter{
Must: []*qdrant.Condition{
qdrant.NewMatch("color", "red"),
},
},
},
{
Query: qdrant.NewQuery(0.01, 0.45, 0.67),
Filter: &qdrant.Filter{
Must: []*qdrant.Condition{
qdrant.NewMatch("color", "green"),
},
},
},
},
Query: qdrant.NewQueryOrderBy(&qdrant.OrderBy{
Key: "price",
}),
})
```
| Parameter | Default | Description |
| --- | --- | --- |
| `x` | N/A | The value to decay |
| `target` | 0.0 | The value at which the decay will be at its peak. For distances it is usually set at 0.0, but can be set to any value. |
| `scale` | 1.0 | The value at which the decay function will be equal to `midpoint`. This is in terms of `x` units, for example, if `x` is in meters, `scale` of 5000 means 5km. Must be a non-zero positive number |
| `midpoint` | 0.5 | Output is `midpoint` when `x` equals `scale`. Must be in the range (0.0, 1.0), exclusive |

In this example, we first fetch 10 points with the color `"red"` and then 10 points with the color `"green"`.
Then, we order the results by the price field.
The formulas for each decay function are as follows:
<iframe src="https://www.desmos.com/calculator/idv5hknwb1?embed" width="600" height="400" style="border: 1px solid #ccc" frameborder=0></iframe>

This is how we can guarantee even sampling of both colors in the results and also get the cheapest ones first.
| Decay Function | Formula | Range |
| --- | --- | --- |
| Linear (green) | $ \max\left(0,\ -\frac{\left(1-m_{idpoint}\right)}{s_{cale}}\cdot {abs}\left(x-t_{arget}\right)+1\right) $ | $[0, 1]$ |
| Exponential (red) | $ \exp\left(\frac{\ln\left(m_{idpoint}\right)}{s_{cale}}\cdot {abs}\left(x-t_{arget}\right)\right) $ | $(0, 1]$ |
| Gaussian (purple) | $ \exp\left(\frac{\ln\left(m_{idpoint}\right)}{s_{cale}^{2}}\cdot {abs}\left(x-t_{arget}\right)^{2}\right) $ | $(0, 1]$ |

## Grouping

Expand Down