mirror of
https://github.com/qdrant/qdrant.git
synced 2026-08-05 01:20:53 -05:00
564 lines
14 KiB
YAML
564 lines
14 KiB
YAML
openapi: 3.0.1
|
|
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 POST 'http://localhost:6333/collections' \
|
|
-H 'Content-Type: application/json' \
|
|
--data-raw '{
|
|
"create_collection": {
|
|
"name": "test_collection",
|
|
"vector_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": {
|
|
"vectors_count": 0,
|
|
"segments_count": 5,
|
|
"disk_data_size": 0,
|
|
"ram_data_size": 0,
|
|
"config": {
|
|
"vector_size": 4,
|
|
"index": {
|
|
"type": "plain",
|
|
"options": {}
|
|
},
|
|
"distance": "Dot",
|
|
"storage_type": {
|
|
"type": "in_memory"
|
|
}
|
|
}
|
|
},
|
|
"status": "ok",
|
|
"time": 2.1199e-05
|
|
}
|
|
|
|
```
|
|
|
|
|
|
### Add points
|
|
|
|
Let's now add vectors with some payload:
|
|
|
|
```
|
|
|
|
curl -L -X POST 'http://localhost:6333/collections/test_collection?wait=true' \
|
|
-H 'Content-Type: application/json' \
|
|
--data-raw '{
|
|
"upsert_points": {
|
|
"points": [
|
|
{"id": 1, "vector": [0.05, 0.61, 0.76, 0.74], "payload": {"city": {"type": "keyword", "value": "Berlin"}}},
|
|
{"id": 2, "vector": [0.19, 0.81, 0.75, 0.11], "payload": {"city": {"type": "keyword", "value": ["Berlin", "London"] }}},
|
|
{"id": 3, "vector": [0.36, 0.55, 0.47, 0.94], "payload": {"city": {"type": "keyword", "value": ["Berlin", "Moscow"] }}},
|
|
{"id": 4, "vector": [0.18, 0.01, 0.85, 0.80], "payload": {"city": {"type": "keyword", "value": ["London", "Moscow"]}}},
|
|
{"id": 5, "vector": [0.24, 0.18, 0.22, 0.44], "payload": {"count": {"type": "integer", "value": [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 },
|
|
{ "id": 1, "score": 1.273 },
|
|
{ "id": 3, "score": 1.208 }
|
|
],
|
|
"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": {
|
|
"keyword": "London"
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"vector": [0.2, 0.1, 0.9, 0.7],
|
|
"top": 3
|
|
}'
|
|
|
|
```
|
|
|
|
Expected response:
|
|
|
|
```
|
|
|
|
{
|
|
"result": [
|
|
{ "id": 4, "score": 1.362 },
|
|
{ "id": 2, "score": 0.871 }
|
|
],
|
|
"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: 0.1.0
|
|
externalDocs:
|
|
description: Find out more about Qdrant aplications and demo
|
|
url: demo.qdrant.tech
|
|
servers:
|
|
- url: http://localhost:6333
|
|
tags:
|
|
- name: collections
|
|
description: Searchable collections of points.
|
|
- name: points
|
|
description: Float-point vectors with payload.
|
|
|
|
paths:
|
|
/collections:
|
|
get:
|
|
tags:
|
|
- collections
|
|
summary: Get list of existing collections
|
|
operationId: get_collections
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
time:
|
|
type: number
|
|
format: float
|
|
description: Time spent to process this request
|
|
status:
|
|
type: string
|
|
enum: ["ok"]
|
|
result:
|
|
$ref: "./models.json#/components/schemas/CollectionsResponse"
|
|
default:
|
|
description: error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
post:
|
|
tags:
|
|
- collections
|
|
summary: Perform update operation on collections
|
|
operationId: update_collections
|
|
requestBody:
|
|
description: Operation to perform on collections
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "./models.json#/components/schemas/StorageOperations"
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
time:
|
|
type: number
|
|
format: float
|
|
description: Time spent to process this request
|
|
status:
|
|
type: string
|
|
enum: ["ok"]
|
|
result:
|
|
type: boolean
|
|
default:
|
|
description: error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/collections/{name}:
|
|
get:
|
|
tags:
|
|
- collections
|
|
summary: Get information about existing collection
|
|
operationId: get_collection
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: Name of the collection to retrieve
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
time:
|
|
type: number
|
|
format: float
|
|
description: Time spent to process this request
|
|
status:
|
|
type: string
|
|
enum: ["ok"]
|
|
result:
|
|
$ref: "./models.json#/components/schemas/CollectionInfo"
|
|
default:
|
|
description: error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
post:
|
|
tags:
|
|
- points
|
|
summary: Update points (vectors, payloads, indexes) in collection
|
|
operationId: update_points
|
|
requestBody:
|
|
description: Collection update operations
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "./models.json#/components/schemas/CollectionUpdateOperations"
|
|
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: Name of the collection to search in
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: wait
|
|
in: query
|
|
description: "Wait for changes to actually happen? Default: false"
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
time:
|
|
type: number
|
|
format: float
|
|
description: Time spent to process this request
|
|
status:
|
|
type: string
|
|
enum: [ "ok" ]
|
|
result:
|
|
$ref: "./models.json#/components/schemas/UpdateResult"
|
|
default:
|
|
description: error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
|
|
/collections/{name}/points/{id}:
|
|
get:
|
|
tags:
|
|
- points
|
|
summary: Retrieve point by id
|
|
operationId: get_point
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: Name of the collection to retrieve from
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: id
|
|
in: path
|
|
description: Id of the point
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
time:
|
|
type: number
|
|
format: float
|
|
description: Time spent to process this request
|
|
status:
|
|
type: string
|
|
enum: ["ok"]
|
|
result:
|
|
$ref: "./models.json#/components/schemas/Record"
|
|
default:
|
|
description: error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/collections/{name}/points:
|
|
post:
|
|
tags:
|
|
- points
|
|
summary: Retrieve points by ids
|
|
operationId: get_points
|
|
requestBody:
|
|
description: List of points to retrieve
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "./models.json#/components/schemas/PointRequest"
|
|
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: Name of the collection to retrieve from
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
time:
|
|
type: number
|
|
format: float
|
|
description: Time spent to process this request
|
|
status:
|
|
type: string
|
|
enum: ["ok"]
|
|
result:
|
|
type: array
|
|
items:
|
|
$ref: "./models.json#/components/schemas/Record"
|
|
default:
|
|
description: error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/collections/{name}/points/search:
|
|
post:
|
|
tags:
|
|
- points
|
|
summary: Search points
|
|
operationId: search_points
|
|
requestBody:
|
|
description: Search request with optional filtering
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "./models.json#/components/schemas/SearchRequest"
|
|
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: Name of the collection to search in
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
time:
|
|
type: number
|
|
format: float
|
|
description: Time spent to process this request
|
|
status:
|
|
type: string
|
|
enum: ["ok"]
|
|
result:
|
|
type: array
|
|
items:
|
|
$ref: "./models.json#/components/schemas/ScoredPoint"
|
|
default:
|
|
description: error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
/collections/{name}/points/recommend:
|
|
post:
|
|
tags:
|
|
- points
|
|
summary: Recommend points
|
|
operationId: recommend_points
|
|
requestBody:
|
|
description: Request points based on positive and negative examples.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "./models.json#/components/schemas/RecommendRequest"
|
|
|
|
parameters:
|
|
- name: name
|
|
in: path
|
|
description: Name of the collection to search in
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
200:
|
|
description: successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
time:
|
|
type: number
|
|
format: float
|
|
description: Time spent to process this request
|
|
status:
|
|
type: string
|
|
enum: ["ok"]
|
|
result:
|
|
type: array
|
|
items:
|
|
$ref: "./models.json#/components/schemas/ScoredPoint"
|
|
default:
|
|
description: error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ErrorResponse"
|
|
|
|
|
|
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
|
|
|