Payload

One of the important features of Qdrant is the ability to store additional information outside of vectors (storage management business attributes). In Qdrant terminology, this additional information is referred to as "payload".

Qdrant allows you to store any information that can be represented using JSON.

Here is an example of a typical payload:

{
    "name": "jacket",
    "color": ["red", "blue"],
    "quantity": 10,
    "price": 11.99,
    "location": [
        {
            "longitude": 52.5200,
            "latitude": 13.4050
        }
    ],
    "reviews": [
        {
            "user": "Alice",
            "score": 4
        },
        {
            "user": "Bob",
            "score": 5
        }
    ]
}

Payload Types

In addition to storing payloads, Qdrant also allows you to search based on certain types of values. This feature is implemented as additional filters during the search process and allows you to embed custom logic on top of semantic similarity.

During the filtering process, Qdrant will check the conditions of values that meet the filter criteria. If the stored value type does not meet the filter criteria, it is considered unsatisfactory.

For example, applying range conditions to string data will result in an empty output.

However, the handling of arrays (multiple values of the same type) is slightly different. When we apply filters to an array, if at least one value in the array meets the condition, the filter will succeed.

A detailed discussion of the filtering process is carried out in the filtering section.

Let's take a look at the data types supported by Qdrant:

Integer

integer - 64-bit integer, ranging from -9223372036854775808 to 9223372036854775807.

Examples of single and multiple integer values:

{
    "quantity": 10,
    "sizes": [35, 36, 38]
}

Float

float - 64-bit floating point number.

Examples of single and multiple float values:

{
    "price": 11.99,
    "rating": [9.1, 9.2, 9.4]
}

Boolean

bool - binary value. Equal to true or false.

Examples of single and multiple bool values:

{
    "delivered": true,
    "replies": [false, false, true, false]
}

Keyword

keyword - string value.

Examples of single and multiple keyword values:

{
    "name": "Alice",
    "friends": [
        "Bob",
        "Eva",
        "Jack"
    ]
}

Geographic Coordinates

geo is used to represent geographic coordinates.

Examples of single and multiple geo values:

{
    "location": {
        "longitude": 52.5200,
        "latitude": 13.4050
    },
    "cities": [
        {
            "longitude": 51.5072,
            "latitude": 0.1276
        },
        {
            "longitude": 40.7128,
            "latitude": 74.0060
        }
    ]
}

Coordinates should be described as an object containing two fields: longitude - representing longitude, latitude - representing latitude.

Creating points with payloads

REST API (architecture)

PUT /collections/{collection_name}/points

{
    "points": [
        {
            "id": 1,
            "vector": [0.05, 0.61, 0.76, 0.74],
            "payload": {"city": "Berlin", "price": 1.99}
        },
        {
            "id": 2,
            "vector": [0.19, 0.81, 0.75, 0.11],
            "payload": {"city": ["Berlin", "London"], "price": 1.99}
        },
        {
            "id": 3,
            "vector": [0.36, 0.55, 0.47, 0.94],
            "payload": {"city": ["Berlin", "Moscow"], "price": [1.99, 2.99]}
        }
    ]
}

Setting payloads

REST API (Schema):

POST /collections/{collection_name}/points/payload

{
    "payload": {
        "property1": "string",
        "property2": "string"
    },
    "points": [
        0, 3, 100
    ]
}

Deleting payloads

This method removes specified payload keys from the specified points.

REST API (Schema):

POST /collections/{collection_name}/points/payload/delete

{
    "keys": ["color", "price"],
    "points": [0, 3, 100]
}

Clearing payloads

This method removes all payload keys from the specified points.

REST API (Schema):

POST /collections/{collection_name}/points/payload/clear

{
    "points": [0, 3, 100]
}

You can also use models.FilterSelector to remove points that match given filter conditions, instead of providing IDs.

Payload indexing

To efficiently conduct filtered searches, Qdrant allows you to create an index for payload fields by specifying the name and type of the field.

Indexed fields also impact the vector index.

In practice, it is recommended to create indexes on fields that are likely to restrict the results the most. For example, indexing on the object ID will be more efficient than indexing on color, as the object ID is unique for each record, while color only has a few possible values.

In composite queries involving multiple fields, Qdrant will attempt to use the most restrictive index first.

To create an index for a field, the following can be used:

REST API (Schema)

PUT /collections/{collection_name}/index

{
    "field_name": "name of field to index",
    "field_schema": "keyword"
}

The indexed fields are displayed in the payload schema together with the collection info API.

Example payload schema:

{
    "payload_schema": {
        "property1": {
            "data_type": "keyword"
        },
        "property2": {
            "data_type": "integer"
        }
    }
}