openapi: 3.0.1
info:
title: Qdrant Aliases Distributed API
description: "API description for Qdrant vector search engine.\n\nThis document describes CRUD and search operations on collections of points (vectors with payload).\n\nQdrant supports any combinations of `should`, `min_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.\n## Examples\nThis examples cover the most basic use-cases - collection creation and basic vector search.\n### Create collection\nFirst - let's create a collection with dot-production metric.\n```\ncurl -X PUT 'http://localhost:6333/collections/test_collection' \\\n -H 'Content-Type: application/json' \\\n --data-raw '{\n \"vectors\": {\n \"size\": 4,\n \"distance\": \"Dot\"\n }\n }'\n\n```\nExpected response:\n```\n{\n \"result\": true,\n \"status\": \"ok\",\n \"time\": 0.031095451\n}\n```\nWe can ensure that collection was created:\n```\ncurl 'http://localhost:6333/collections/test_collection'\n```\nExpected response:\n```\n{\n \"result\": {\n \"status\": \"green\",\n \"segments_count\": 5,\n \"disk_data_size\": 0,\n \"ram_data_size\": 0,\n \"config\": {\n \"params\": {\n \"vectors\": {\n \"size\": 4,\n \"distance\": \"Dot\"\n }\n },\n \"hnsw_config\": {\n \"m\": 16,\n \"ef_construct\": 100,\n \"full_scan_threshold\": 10000\n },\n \"optimizer_config\": {\n \"deleted_threshold\": 0.2,\n \"vacuum_min_vector_number\": 1000,\n \"default_segment_number\": 2,\n \"max_segment_size\": null,\n \"memmap_threshold\": null,\n \"indexing_threshold\": 20000,\n \"flush_interval_sec\": 5,\n \"max_optimization_threads\": null\n },\n \"wal_config\": {\n \"wal_capacity_mb\": 32,\n \"wal_segments_ahead\": 0\n }\n }\n },\n \"status\": \"ok\",\n \"time\": 2.1199e-05\n}\n```\n\n### Add points\nLet's now add vectors with some payload:\n```\ncurl -L -X PUT 'http://localhost:6333/collections/test_collection/points?wait=true' \\ -H 'Content-Type: application/json' \\ --data-raw '{\n \"points\": [\n {\"id\": 1, \"vector\": [0.05, 0.61, 0.76, 0.74], \"payload\": {\"city\": \"Berlin\"}},\n {\"id\": 2, \"vector\": [0.19, 0.81, 0.75, 0.11], \"payload\": {\"city\": [\"Berlin\", \"London\"] }},\n {\"id\": 3, \"vector\": [0.36, 0.55, 0.47, 0.94], \"payload\": {\"city\": [\"Berlin\", \"Moscow\"] }},\n {\"id\": 4, \"vector\": [0.18, 0.01, 0.85, 0.80], \"payload\": {\"city\": [\"London\", \"Moscow\"] }},\n {\"id\": 5, \"vector\": [0.24, 0.18, 0.22, 0.44], \"payload\": {\"count\": [0]}},\n {\"id\": 6, \"vector\": [0.35, 0.08, 0.11, 0.44]}\n ]\n}'\n```\nExpected response:\n```\n{\n \"result\": {\n \"operation_id\": 0,\n \"status\": \"completed\"\n },\n \"status\": \"ok\",\n \"time\": 0.000206061\n}\n```\n### Search with filtering\nLet's start with a basic request:\n```\ncurl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \\ -H 'Content-Type: application/json' \\ --data-raw '{\n \"vector\": [0.2,0.1,0.9,0.7],\n \"top\": 3\n}'\n```\nExpected response:\n```\n{\n \"result\": [\n { \"id\": 4, \"score\": 1.362, \"payload\": null, \"version\": 0 },\n { \"id\": 1, \"score\": 1.273, \"payload\": null, \"version\": 0 },\n { \"id\": 3, \"score\": 1.208, \"payload\": null, \"version\": 0 }\n ],\n \"status\": \"ok\",\n \"time\": 0.000055785\n}\n```\nBut result is different if we add a filter:\n```\ncurl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \\ -H 'Content-Type: application/json' \\ --data-raw '{\n \"filter\": {\n \"should\": [\n {\n \"key\": \"city\",\n \"match\": {\n \"value\": \"London\"\n }\n }\n ]\n },\n \"vector\": [0.2, 0.1, 0.9, 0.7],\n \"top\": 3\n}'\n```\nExpected response:\n```\n{\n \"result\": [\n { \"id\": 4, \"score\": 1.362, \"payload\": null, \"version\": 0 },\n { \"id\": 2, \"score\": 0.871, \"payload\": null, \"version\": 0 }\n ],\n \"status\": \"ok\",\n \"time\": 0.000093972\n}\n```\n"
contact:
email: andrey@vasnetsov.com
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: master
servers:
- url: '{protocol}://{hostname}:{port}'
variables:
protocol:
enum:
- http
- https
default: http
hostname:
default: localhost
port:
default: '6333'
security:
- api-key: []
- bearerAuth: []
- {}
tags:
- name: Distributed
description: Service distributed setup.
paths:
/collections/{collection_name}/shards:
put:
tags:
- Distributed
summary: Create shard key
operationId: create_shard_key
requestBody:
description: Shard key configuration
content:
application/json:
schema:
$ref: '#/components/schemas/CreateShardingKey'
parameters:
- name: collection_name
in: path
description: Name of the collection to create shards for
required: true
schema:
type: string
- name: timeout
in: query
description: 'Wait for operation commit timeout in seconds.
If timeout is reached - request will return with service error.
'
schema:
type: integer
responses:
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
usage:
default: null
anyOf:
- $ref: '#/components/schemas/Usage'
- nullable: true
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
get:
tags:
- Distributed
summary: List shard keys
operationId: list_shard_keys
parameters:
- name: collection_name
in: path
description: Name of the collection to list shard keys for
required: true
schema:
type: string
responses:
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
usage:
default: null
anyOf:
- $ref: '#/components/schemas/Usage'
- nullable: true
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
$ref: '#/components/schemas/ShardKeysResponse'
/collections/{collection_name}/shards/delete:
post:
tags:
- Distributed
summary: Delete shard key
operationId: delete_shard_key
requestBody:
description: Select shard key to delete
content:
application/json:
schema:
$ref: '#/components/schemas/DropShardingKey'
parameters:
- name: collection_name
in: path
description: Name of the collection to create shards for
required: true
schema:
type: string
- name: timeout
in: query
description: 'Wait for operation commit timeout in seconds.
If timeout is reached - request will return with service error.
'
schema:
type: integer
responses:
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
usage:
default: null
anyOf:
- $ref: '#/components/schemas/Usage'
- nullable: true
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
/cluster:
get:
tags:
- Distributed
summary: Get cluster status info
description: Get information about the current state and composition of the cluster
operationId: cluster_status
responses:
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
usage:
default: null
anyOf:
- $ref: '#/components/schemas/Usage'
- nullable: true
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
$ref: '#/components/schemas/ClusterStatus'
/cluster/telemetry:
get:
tags:
- Distributed
summary: Collect cluster telemetry data
description: Get telemetry data, from the point of view of the cluster. This includes peers info, collections info, shard transfers, and resharding status
operationId: cluster_telemetry
parameters:
- name: details_level
in: query
description: The level of detail to include in the response
required: false
schema:
type: integer
- name: timeout
in: query
description: Timeout for this request
required: false
schema:
type: integer
minimum: 1
default: 60
responses:
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
usage:
default: null
anyOf:
- $ref: '#/components/schemas/Usage'
- nullable: true
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
$ref: '#/components/schemas/DistributedTelemetryData'
/cluster/recover:
post:
tags:
- Distributed
summary: Tries to recover current peer Raft state.
operationId: recover_current_peer
responses:
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
usage:
default: null
anyOf:
- $ref: '#/components/schemas/Usage'
- nullable: true
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
/cluster/peer/{peer_id}:
delete:
tags:
- Distributed
summary: Remove peer from the cluster
description: Tries to remove peer from the cluster. Will return an error if peer has shards on it.
operationId: remove_peer
parameters:
- name: peer_id
in: path
description: Id of the peer
required: true
schema:
type: integer
- name: timeout
in: query
description: 'Wait for operation commit timeout in seconds.
If timeout is reached - request will return with service error.
'
schema:
type: integer
- name: force
in: query
description: If true - removes peer even if it has shards/replicas on it.
schema:
type: boolean
default: false
responses:
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
usage:
default: null
anyOf:
- $ref: '#/components/schemas/Usage'
- nullable: true
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
/collections/{collection_name}/cluster:
get:
tags:
- Distributed
summary: Collection cluster info
description: Get cluster information for a collection
operationId: collection_cluster_info
parameters:
- name: collection_name
in: path
description: Name of the collection to retrieve the cluster info for
required: true
schema:
type: string
responses:
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
usage:
default: null
anyOf:
- $ref: '#/components/schemas/Usage'
- nullable: true
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
$ref: '#/components/schemas/CollectionClusterInfo'
post:
tags:
- Distributed
summary: Update collection cluster setup
operationId: update_collection_cluster
requestBody:
description: Collection cluster update operations
content:
application/json:
schema:
$ref: '#/components/schemas/ClusterOperations'
parameters:
- name: collection_name
in: path
description: Name of the collection on which to to apply the cluster update operation
required: true
schema:
type: string
- name: timeout
in: query
description: 'Wait for operation commit timeout in seconds.
If timeout is reached - request will return with service error.
'
schema:
type: integer
responses:
default:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
4XX:
description: error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'200':
description: successful operation
content:
application/json:
schema:
type: object
properties:
usage:
default: null
anyOf:
- $ref: '#/components/schemas/Usage'
- nullable: true
time:
type: number
format: float
description: Time spent to process this request
example: 0.002
status:
type: string
example: ok
result:
type: boolean
components:
schemas:
DropShardingKey:
type: object
required:
- shard_key
properties:
shard_key:
$ref: '#/components/schemas/ShardKey'
DistributedClusterTelemetry:
type: object
required:
- enabled
- peers
properties:
enabled:
type: boolean
number_of_peers:
type: integer
format: uint64
minimum: 0
nullable: true
peers:
type: object
additionalProperties:
$ref: '#/components/schemas/DistributedPeerInfo'
ReshardingInfo:
type: object
required:
- direction
- peer_id
- shard_id
properties:
direction:
$ref: '#/components/schemas/ReshardingDirection'
shard_id:
type: integer
format: uint32
minimum: 0
peer_id:
type: integer
format: uint64
minimum: 0
shard_key:
anyOf:
- $ref: '#/components/schemas/ShardKey'
- nullable: true
IsNullCondition:
description: Select points with null payload for a specified field
type: object
required:
- is_null
properties:
is_null:
$ref: '#/components/schemas/PayloadField'
FieldCondition:
description: All possible payload filtering conditions
type: object
required:
- key
properties:
key:
description: Payload key
type: string
match:
description: Check if point has field with a given value
anyOf:
- $ref: '#/components/schemas/Match'
- nullable: true
range:
description: Check if points value lies in a given range
anyOf:
- $ref: '#/components/schemas/RangeInterface'
- nullable: true
geo_bounding_box:
description: Check if points geolocation lies in a given area
anyOf:
- $ref: '#/components/schemas/GeoBoundingBox'
- nullable: true
geo_radius:
description: Check if geo point is within a given radius
anyOf:
- $ref: '#/components/schemas/GeoRadius'
- nullable: true
geo_polygon:
description: Check if geo point is within a given polygon
anyOf:
- $ref: '#/components/schemas/GeoPolygon'
- nullable: true
values_count:
description: Check number of values of the field
anyOf:
- $ref: '#/components/schemas/ValuesCount'
- nullable: true
is_empty:
description: 'Check that the field is empty, alternative syntax for `is_empty: "field_name"`'
type: boolean
nullable: true
is_null:
description: 'Check that the field is null, alternative syntax for `is_null: "field_name"`'
type: boolean
nullable: true
HasIdCondition:
description: ID-based filtering condition
type: object
required:
- has_id
properties:
has_id:
type: array
items:
$ref: '#/components/schemas/ExtendedPointId'
uniqueItems: true
ShardCleanStatusFailedTelemetry:
type: object
required:
- reason
properties:
reason:
type: string
GeoLineString:
description: Ordered sequence of GeoPoints representing the line
type: object
required:
- points
properties:
points:
type: array
items:
$ref: '#/components/schemas/GeoPoint'
AbortReshardingOperation:
type: object
required:
- abort_resharding
properties:
abort_resharding:
$ref: '#/components/schemas/AbortResharding'
IsEmptyCondition:
description: Select points with empty payload for a specified field
type: object
required:
- is_empty
properties:
is_empty:
$ref: '#/components/schemas/PayloadField'
Usage:
description: Usage of the hardware resources, spent to process the request
type: object
properties:
hardware:
anyOf:
- $ref: '#/components/schemas/HardwareUsage'
- nullable: true
inference:
anyOf:
- $ref: '#/components/schemas/InferenceUsage'
- nullable: true
Filter:
type: object
properties:
should:
description: At least one of those conditions should match
anyOf:
- $ref: '#/components/schemas/Condition'
- type: array
items:
$ref: '#/components/schemas/Condition'
- nullable: true
min_should:
description: At least minimum amount of given conditions should match
anyOf:
- $ref: '#/components/schemas/MinShould'
- nullable: true
must:
description: All conditions must match
anyOf:
- $ref: '#/components/schemas/Condition'
- type: array
items:
$ref: '#/components/schemas/Condition'
- nullable: true
must_not:
description: All conditions must NOT match
anyOf:
- $ref: '#/components/schemas/Condition'
- type: array
items:
$ref: '#/components/schemas/Condition'
- nullable: true
additionalProperties: false
ExtendedPointId:
description: Type, used for specifying point ID in user interface
anyOf:
- type: integer
format: uint64
minimum: 0
example: 42
- type: string
format: uuid
example: 550e8400-e29b-41d4-a716-446655440000
InferenceUsage:
type: object
required:
- models
properties:
models:
type: object
additionalProperties:
$ref: '#/components/schemas/ModelUsage'
MoveShard:
type: object
required:
- from_peer_id
- shard_id
- to_peer_id
properties:
shard_id:
type: integer
format: uint32
minimum: 0
to_peer_id:
type: integer
format: uint64
minimum: 0
from_peer_id:
type: integer
format: uint64
minimum: 0
method:
description: Method for transferring the shard from one node to another
anyOf:
- $ref: '#/components/schemas/ShardTransferMethod'
- nullable: true
ShardTransferInfo:
type: object
required:
- from
- shard_id
- sync
- to
properties:
shard_id:
type: integer
format: uint32
minimum: 0
to_shard_id:
description: 'Target shard ID if different than source shard ID
Used exclusively with `ReshardingStreamRecords` transfer method.'
type: integer
format: uint32
minimum: 0
nullable: true
from:
description: Source peer id
type: integer
format: uint64
minimum: 0
to:
description: Destination peer id
type: integer
format: uint64
minimum: 0
sync:
description: If `true` transfer is a synchronization of a replicas If `false` transfer is a moving of a shard from one peer to another
type: boolean
method:
anyOf:
- $ref: '#/components/schemas/ShardTransferMethod'
- nullable: true
comment:
description: A human-readable report of the transfer progress. Available only on the source peer.
type: string
nullable: true
LocalShardInfo:
type: object
required:
- points_count
- shard_id
- state
properties:
shard_id:
description: Local shard id
type: integer
format: uint32
minimum: 0
shard_key:
description: User-defined sharding key
anyOf:
- $ref: '#/components/schemas/ShardKey'
- nullable: true
points_count:
description: Number of points in the shard
type: integer
format: uint
minimum: 0
state:
$ref: '#/components/schemas/ReplicaState'
ShardKey:
anyOf:
- type: string
example: region_1
- type: integer
format: uint64
minimum: 0
example: 12
ReshardingDirection:
description: 'Resharding direction, scale up or down in number of shards
- `up` - Scale up, add a new shard
- `down` - Scale down, remove a shard'
type: string
enum:
- up
- down
HasVectorCondition:
description: Filter points which have specific vector assigned
type: object
required:
- has_vector
properties:
has_vector:
type: string
ConsensusThreadStatus:
description: Information about current consensus thread status
oneOf:
- type: object
required:
- consensus_thread_status
- last_update
properties:
consensus_thread_status:
type: string
enum:
- working
last_update:
type: string
format: date-time
- type: object
required:
- consensus_thread_status
properties:
consensus_thread_status:
type: string
enum:
- stopped
- type: object
required:
- consensus_thread_status
- err
properties:
consensus_thread_status:
type: string
enum:
- stopped_with_err
err:
type: string
ShardCleanStatusTelemetry:
oneOf:
- type: string
enum:
- started
- done
- cancelled
- type: object
required:
- progress
properties:
progress:
$ref: '#/components/schemas/ShardCleanStatusProgressTelemetry'
additionalProperties: false
- type: object
required:
- failed
properties:
failed:
$ref: '#/components/schemas/ShardCleanStatusFailedTelemetry'
additionalProperties: false
DropReplicaOperation:
type: object
required:
- drop_replica
properties:
drop_replica:
$ref: '#/components/schemas/Replica'
MatchAny:
description: Exact match on any of the given values
type: object
required:
- any
properties:
any:
$ref: '#/components/schemas/AnyVariants'
StartResharding:
type: object
required:
- direction
properties:
direction:
$ref: '#/components/schemas/ReshardingDirection'
peer_id:
type: integer
format: uint64
minimum: 0
nullable: true
shard_key:
anyOf:
- $ref: '#/components/schemas/ShardKey'
- nullable: true
MatchPhrase:
description: Full-text phrase match of the string.
type: object
required:
- phrase
properties:
phrase:
type: string
PeerInfo:
description: Information of a peer in the cluster
type: object
required:
- uri
properties:
uri:
type: string
RaftInfo:
description: Summary information about the current raft state
type: object
required:
- commit
- is_voter
- pending_operations
- term
properties:
term:
description: Raft divides time into terms of arbitrary length, each beginning with an election. If a candidate wins the election, it remains the leader for the rest of the term. The term number increases monotonically. Each server stores the current term number which is also exchanged in every communication.
type: integer
format: uint64
minimum: 0
commit:
description: The index of the latest committed (finalized) operation that this peer is aware of.
type: integer
format: uint64
minimum: 0
pending_operations:
description: Number of consensus operations pending to be applied on this peer
type: integer
format: uint
minimum: 0
leader:
description: Leader of the current term
type: integer
format: uint64
minimum: 0
nullable: true
role:
description: Role of this peer in the current term
anyOf:
- $ref: '#/components/schemas/StateRole'
- nullable: true
is_voter:
description: Is this peer a voter or a learner
type: boolean
StateRole:
description: Role
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/qdrant/refs/heads/main/openapi/qdrant-distributed-api-openapi.yml