openapi: 3.0.1
info:
title: Qdrant Aliases 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: Aliases
description: Additional names for existing collections.
paths:
/collections/aliases:
post:
tags:
- Aliases
summary: Update aliases of the collections
operationId: update_aliases
requestBody:
description: Alias update operations
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeAliasesOperation'
parameters:
- 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
/collections/{collection_name}/aliases:
get:
tags:
- Aliases
summary: List aliases for collection
description: Get list of all aliases for a collection
operationId: get_collection_aliases
parameters:
- name: collection_name
in: path
description: Name of the collection
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/CollectionsAliasesResponse'
/aliases:
get:
tags:
- Aliases
summary: List collections aliases
description: Get list of all existing collections aliases
operationId: get_collections_aliases
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/CollectionsAliasesResponse'
components:
schemas:
HardwareUsage:
description: Usage of the hardware resources, spent to process the request
type: object
required:
- cpu
- payload_index_io_read
- payload_index_io_write
- payload_io_read
- payload_io_write
- vector_io_read
- vector_io_write
properties:
cpu:
type: integer
format: uint
minimum: 0
payload_io_read:
type: integer
format: uint
minimum: 0
payload_io_write:
type: integer
format: uint
minimum: 0
payload_index_io_read:
type: integer
format: uint
minimum: 0
payload_index_io_write:
type: integer
format: uint
minimum: 0
vector_io_read:
type: integer
format: uint
minimum: 0
vector_io_write:
type: integer
format: uint
minimum: 0
AliasOperations:
description: Group of all the possible operations related to collection aliases
anyOf:
- $ref: '#/components/schemas/CreateAliasOperation'
- $ref: '#/components/schemas/DeleteAliasOperation'
- $ref: '#/components/schemas/RenameAliasOperation'
CreateAliasOperation:
type: object
required:
- create_alias
properties:
create_alias:
$ref: '#/components/schemas/CreateAlias'
DeleteAlias:
description: Delete alias if exists
type: object
required:
- alias_name
properties:
alias_name:
type: string
RenameAlias:
description: Change alias to a new one
type: object
required:
- new_alias_name
- old_alias_name
properties:
old_alias_name:
type: string
new_alias_name:
type: string
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
AliasDescription:
type: object
required:
- alias_name
- collection_name
properties:
alias_name:
type: string
collection_name:
type: string
example:
alias_name: blogs-title
collection_name: arivx-title
RenameAliasOperation:
description: Change alias to a new one
type: object
required:
- rename_alias
properties:
rename_alias:
$ref: '#/components/schemas/RenameAlias'
CreateAlias:
description: Create alternative name for a collection. Collection will be available under both names for search, retrieve,
type: object
required:
- alias_name
- collection_name
properties:
collection_name:
type: string
alias_name:
type: string
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
InferenceUsage:
type: object
required:
- models
properties:
models:
type: object
additionalProperties:
$ref: '#/components/schemas/ModelUsage'
ModelUsage:
type: object
required:
- tokens
properties:
tokens:
type: integer
format: uint64
minimum: 0
DeleteAliasOperation:
description: Delete alias if exists
type: object
required:
- delete_alias
properties:
delete_alias:
$ref: '#/components/schemas/DeleteAlias'
CollectionsAliasesResponse:
type: object
required:
- aliases
properties:
aliases:
type: array
items:
$ref: '#/components/schemas/AliasDescription'
ChangeAliasesOperation:
description: Operation for performing changes of collection aliases. Alias changes are atomic, meaning that no collection modifications can happen between alias operations.
type: object
required:
- actions
properties:
actions:
type: array
items:
$ref: '#/components/schemas/AliasOperations'
securitySchemes:
api-key:
type: apiKey
in: header
name: api-key
description: Authorization key, either read-write or read-only
bearerAuth:
type: http
scheme: bearer
externalDocs:
description: Find out more about Qdrant applications and demo
url: https://qdrant.tech/documentation/