mirror of
https://github.com/qdrant/qdrant.git
synced 2026-10-03 19:37:41 -05:00
Roman TitovandAndrey Vasnetsov
a50e7bdcd4
* WIP: Add `read_consistency` parameter to the APIs * WIP: Add `read_consistency` parameter to the APIs TODO: - Add documentation * `cargo fmt` * Add gRPC documentation * Add OpenAPI documentation * Cleanup * fixup! Add OpenAPI documentation * fixup! Add gRPC documentation Who would have known there's `generate_grpc_docs.sh`!? 🥲🙈🤦♀️ * generate openapi * Fix `read_consistency` query parameter deserialization * Further improve `read_consistency` query parameter deserialization * `cargo clippy` * Fix `Payload` comparison during read operation result resolving * Fix grammar * rename `read_consistency` -> `consistency` and add integration test * use majority for test * fix tests * Fix tests * fixup! Fix tests Apply the same fix to `ScoredPoint` * Remove an `unwrap` * fixup! Fix tests Gotta love those negative conditions, or how a missed `!` can ruin your day... 🤦♀️ * Make internal API calls strictly "local-shard only" * Implement a few basic traits for `ResolverRecord` * fixup! Implement a few basic traits for `ResolverRecord` * Revert "Make internal API calls strictly "local-shard only"" This reverts commit25378e61ff. * Fix `Record::payload` and `ScoredPoint::payload` serialization * Revert "Fix `Record::payload` and `ScoredPoint::payload` serialization" This reverts commitb566bea49b. * Fix `Record::payload` and `ScoredPoint::payload` visibility * fixup! Fix `Record::payload` and `ScoredPoint::payload` visibility Remove `todo!()` * refactoring --------- Co-authored-by: Andrey Vasnetsov <andrey@vasnetsov.com>
429 lines
11 KiB
YAML
429 lines
11 KiB
YAML
#@ load("openapi.lib.yml", "response", "reference", "type", "array")
|
|
|
|
openapi: 3.0.1
|
|
security: []
|
|
info:
|
|
title: Qdrant API
|
|
description: >
|
|
|
|
API description for Qdrant vector search engine.
|
|
|
|
|
|
This document describes CRUD and search operations on collections of points (vectors with payload).
|
|
|
|
|
|
Qdrant supports any combinations of `should`, `must` and `must_not` conditions,
|
|
which makes it possible to use in applications when object could not be described solely by vector.
|
|
It could be location features, availability flags, and other custom properties businesses should take into account.
|
|
|
|
## Examples
|
|
|
|
This examples cover the most basic use-cases - collection creation and basic vector search.
|
|
|
|
### Create collection
|
|
|
|
First - let's create a collection with dot-production metric.
|
|
|
|
```
|
|
|
|
curl -X PUT 'http://localhost:6333/collections/test_collection' \
|
|
-H 'Content-Type: application/json' \
|
|
--data-raw '{
|
|
"vectors": {
|
|
"size": 4,
|
|
"distance": "Dot"
|
|
}
|
|
}'
|
|
|
|
```
|
|
|
|
Expected response:
|
|
|
|
```
|
|
|
|
{
|
|
"result": true,
|
|
"status": "ok",
|
|
"time": 0.031095451
|
|
}
|
|
|
|
```
|
|
|
|
We can ensure that collection was created:
|
|
|
|
```
|
|
|
|
curl 'http://localhost:6333/collections/test_collection'
|
|
|
|
```
|
|
|
|
Expected response:
|
|
|
|
```
|
|
|
|
{
|
|
"result": {
|
|
"status": "green",
|
|
"vectors_count": 0,
|
|
"segments_count": 5,
|
|
"disk_data_size": 0,
|
|
"ram_data_size": 0,
|
|
"config": {
|
|
"params": {
|
|
"vectors": {
|
|
"size": 4,
|
|
"distance": "Dot"
|
|
}
|
|
},
|
|
"hnsw_config": {
|
|
"m": 16,
|
|
"ef_construct": 100,
|
|
"full_scan_threshold": 10000
|
|
},
|
|
"optimizer_config": {
|
|
"deleted_threshold": 0.2,
|
|
"vacuum_min_vector_number": 1000,
|
|
"max_segment_number": 5,
|
|
"memmap_threshold": 50000,
|
|
"indexing_threshold": 20000,
|
|
"flush_interval_sec": 1
|
|
},
|
|
"wal_config": {
|
|
"wal_capacity_mb": 32,
|
|
"wal_segments_ahead": 0
|
|
}
|
|
}
|
|
},
|
|
"status": "ok",
|
|
"time": 2.1199e-05
|
|
}
|
|
|
|
```
|
|
|
|
|
|
### Add points
|
|
|
|
Let's now add vectors with some payload:
|
|
|
|
```
|
|
|
|
curl -L -X PUT 'http://localhost:6333/collections/test_collection/points?wait=true' \
|
|
-H 'Content-Type: application/json' \
|
|
--data-raw '{
|
|
"points": [
|
|
{"id": 1, "vector": [0.05, 0.61, 0.76, 0.74], "payload": {"city": "Berlin"}},
|
|
{"id": 2, "vector": [0.19, 0.81, 0.75, 0.11], "payload": {"city": ["Berlin", "London"] }},
|
|
{"id": 3, "vector": [0.36, 0.55, 0.47, 0.94], "payload": {"city": ["Berlin", "Moscow"] }},
|
|
{"id": 4, "vector": [0.18, 0.01, 0.85, 0.80], "payload": {"city": ["London", "Moscow"] }},
|
|
{"id": 5, "vector": [0.24, 0.18, 0.22, 0.44], "payload": {"count": [0]}},
|
|
{"id": 6, "vector": [0.35, 0.08, 0.11, 0.44]}
|
|
]
|
|
}'
|
|
|
|
```
|
|
|
|
Expected response:
|
|
|
|
```
|
|
|
|
{
|
|
"result": {
|
|
"operation_id": 0,
|
|
"status": "completed"
|
|
},
|
|
"status": "ok",
|
|
"time": 0.000206061
|
|
}
|
|
|
|
```
|
|
|
|
### Search with filtering
|
|
|
|
Let's start with a basic request:
|
|
|
|
```
|
|
|
|
curl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \
|
|
-H 'Content-Type: application/json' \
|
|
--data-raw '{
|
|
"vector": [0.2,0.1,0.9,0.7],
|
|
"top": 3
|
|
}'
|
|
|
|
```
|
|
|
|
Expected response:
|
|
|
|
```
|
|
|
|
{
|
|
"result": [
|
|
{ "id": 4, "score": 1.362, "payload": null, "version": 0 },
|
|
{ "id": 1, "score": 1.273, "payload": null, "version": 0 },
|
|
{ "id": 3, "score": 1.208, "payload": null, "version": 0 }
|
|
],
|
|
"status": "ok",
|
|
"time": 0.000055785
|
|
}
|
|
|
|
```
|
|
|
|
But result is different if we add a filter:
|
|
|
|
```
|
|
|
|
curl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \
|
|
-H 'Content-Type: application/json' \
|
|
--data-raw '{
|
|
"filter": {
|
|
"should": [
|
|
{
|
|
"key": "city",
|
|
"match": {
|
|
"value": "London"
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"vector": [0.2, 0.1, 0.9, 0.7],
|
|
"top": 3
|
|
}'
|
|
|
|
```
|
|
|
|
Expected response:
|
|
|
|
```
|
|
|
|
{
|
|
"result": [
|
|
{ "id": 4, "score": 1.362, "payload": null, "version": 0 },
|
|
{ "id": 2, "score": 0.871, "payload": null, "version": 0 }
|
|
],
|
|
"status": "ok",
|
|
"time": 0.000093972
|
|
}
|
|
|
|
```
|
|
|
|
contact:
|
|
email: andrey@vasnetsov.com
|
|
license:
|
|
name: Apache 2.0
|
|
url: http://www.apache.org/licenses/LICENSE-2.0.html
|
|
version: master
|
|
externalDocs:
|
|
description: Find out more about Qdrant applications and demo
|
|
url: https://qdrant.tech/documentation/
|
|
servers:
|
|
- url: "{protocol}://{hostname}:{port}"
|
|
variables:
|
|
protocol:
|
|
enum:
|
|
- http
|
|
- https
|
|
default: http
|
|
hostname:
|
|
default: localhost
|
|
port:
|
|
default: "6333"
|
|
tags:
|
|
- name: collections
|
|
description: Searchable collections of points.
|
|
- name: points
|
|
description: Float-point vectors with payload.
|
|
- name: cluster
|
|
description: Service distributed setup
|
|
- name: snapshots
|
|
description: Storage and collections snapshots
|
|
|
|
paths:
|
|
|
|
/collections/{collection_name}/points/scroll:
|
|
post:
|
|
tags:
|
|
- points
|
|
summary: Scroll points
|
|
description: Scroll request - paginate over all points which matches given filtering condition
|
|
operationId: scroll_points
|
|
requestBody:
|
|
description: Pagination and filter parameters
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ScrollRequest"
|
|
|
|
parameters:
|
|
- name: collection_name
|
|
in: path
|
|
description: Name of the collection to retrieve from
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: consistency
|
|
in: query
|
|
description: Define read consistency guarantees for the operation
|
|
required: false
|
|
schema:
|
|
$ref: "#/components/schemas/ReadConsistency"
|
|
responses: #@ response(reference("ScrollResult"))
|
|
|
|
/collections/{collection_name}/points/search:
|
|
post:
|
|
tags:
|
|
- points
|
|
summary: Search points
|
|
description: Retrieve closest points based on vector similarity and given filtering conditions
|
|
operationId: search_points
|
|
requestBody:
|
|
description: Search request with optional filtering
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SearchRequest"
|
|
|
|
parameters:
|
|
- name: collection_name
|
|
in: path
|
|
description: Name of the collection to search in
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: consistency
|
|
in: query
|
|
description: Define read consistency guarantees for the operation
|
|
required: false
|
|
schema:
|
|
$ref: "#/components/schemas/ReadConsistency"
|
|
responses: #@ response(array(reference("ScoredPoint")))
|
|
|
|
/collections/{collection_name}/points/search/batch:
|
|
post:
|
|
tags:
|
|
- points
|
|
summary: Search batch points
|
|
description: Retrieve by batch the closest points based on vector similarity and given filtering conditions
|
|
operationId: search_batch_points
|
|
requestBody:
|
|
description: Search batch request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SearchRequestBatch"
|
|
|
|
parameters:
|
|
- name: collection_name
|
|
in: path
|
|
description: Name of the collection to search in
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: consistency
|
|
in: query
|
|
description: Define read consistency guarantees for the operation
|
|
required: false
|
|
schema:
|
|
$ref: "#/components/schemas/ReadConsistency"
|
|
responses: #@ response(array(array(reference("ScoredPoint"))))
|
|
|
|
/collections/{collection_name}/points/recommend:
|
|
post:
|
|
tags:
|
|
- points
|
|
summary: Recommend points
|
|
description: Look for the points which are closer to stored positive examples and at the same time further to negative examples.
|
|
operationId: recommend_points
|
|
requestBody:
|
|
description: Request points based on positive and negative examples.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RecommendRequest"
|
|
|
|
parameters:
|
|
- name: collection_name
|
|
in: path
|
|
description: Name of the collection to search in
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: consistency
|
|
in: query
|
|
description: Define read consistency guarantees for the operation
|
|
required: false
|
|
schema:
|
|
$ref: "#/components/schemas/ReadConsistency"
|
|
responses: #@ response(array(reference("ScoredPoint")))
|
|
|
|
/collections/{collection_name}/points/recommend/batch:
|
|
post:
|
|
tags:
|
|
- points
|
|
summary: Recommend batch points
|
|
description: Look for the points which are closer to stored positive examples and at the same time further to negative examples.
|
|
operationId: recommend_batch_points
|
|
requestBody:
|
|
description: Request points based on positive and negative examples.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/RecommendRequestBatch"
|
|
|
|
parameters:
|
|
- name: collection_name
|
|
in: path
|
|
description: Name of the collection to search in
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: consistency
|
|
in: query
|
|
description: Define read consistency guarantees for the operation
|
|
required: false
|
|
schema:
|
|
$ref: "#/components/schemas/ReadConsistency"
|
|
responses: #@ response(array(array(reference("ScoredPoint"))))
|
|
|
|
/collections/{collection_name}/points/count:
|
|
post:
|
|
tags:
|
|
- points
|
|
summary: Count points
|
|
description: Count points which matches given filtering condition
|
|
operationId: count_points
|
|
requestBody:
|
|
description: Request counts of points which matches given filtering condition
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CountRequest"
|
|
|
|
parameters:
|
|
- name: collection_name
|
|
in: path
|
|
description: Name of the collection to count in
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses: #@ response(reference("CountResult"))
|
|
|
|
components:
|
|
schemas:
|
|
ErrorResponse:
|
|
type: object
|
|
properties:
|
|
time:
|
|
type: number
|
|
format: float
|
|
description: Time spent to process this request
|
|
status:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
description: Description of the occurred error.
|
|
result:
|
|
type: object
|
|
nullable: true
|
|
|