openapi: 3.0.1
info:
title: Qdrant Aliases Indexes 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: Indexes
description: Indexes for payloads associated with points.
paths:
/collections/{collection_name}/index:
put:
tags:
- Indexes
summary: Create index for field in collection
description: Create index for field in collection
operationId: create_field_index
parameters:
- name: collection_name
in: path
description: Name of the collection
required: true
schema:
type: string
- name: wait
in: query
description: If true, wait for changes to actually happen
required: false
schema:
type: boolean
- name: ordering
in: query
description: define ordering guarantees for the operation
required: false
schema:
$ref: '#/components/schemas/WriteOrdering'
- name: timeout
in: query
description: Timeout for the operation
required: false
schema:
type: integer
minimum: 1
requestBody:
description: Field name
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFieldIndex'
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/UpdateResult'
/collections/{collection_name}/index/{field_name}:
delete:
tags:
- Indexes
summary: Delete index for field in collection
description: Delete field index for collection
operationId: delete_field_index
parameters:
- name: collection_name
in: path
description: Name of the collection
required: true
schema:
type: string
- name: field_name
in: path
description: Name of the field where to delete the index
required: true
schema:
type: string
- name: wait
in: query
description: If true, wait for changes to actually happen
required: false
schema:
type: boolean
- name: ordering
in: query
description: define ordering guarantees for the operation
required: false
schema:
$ref: '#/components/schemas/WriteOrdering'
- name: timeout
in: query
description: Timeout for the operation
required: false
schema:
type: integer
minimum: 1
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/UpdateResult'
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
KeywordIndexType:
type: string
enum:
- keyword
TextIndexParams:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/TextIndexType'
tokenizer:
$ref: '#/components/schemas/TokenizerType'
min_token_len:
description: Minimum characters to be tokenized.
type: integer
format: uint
minimum: 0
nullable: true
max_token_len:
description: Maximum characters to be tokenized.
type: integer
format: uint
minimum: 0
nullable: true
lowercase:
description: 'If true, lowercase all tokens. Default: true.'
type: boolean
nullable: true
ascii_folding:
description: 'If true, normalize tokens by folding accented characters to ASCII (e.g., "ação" -> "acao"). Default: false.'
type: boolean
nullable: true
phrase_matching:
description: 'If true, support phrase matching. Default: false.'
type: boolean
nullable: true
stopwords:
description: Ignore this set of tokens. Can select from predefined languages and/or provide a custom set.
anyOf:
- $ref: '#/components/schemas/StopwordsInterface'
- nullable: true
on_disk:
description: 'If true, store the index on disk. Default: false.'
type: boolean
nullable: true
stemmer:
description: 'Algorithm for stemming. Default: disabled.'
anyOf:
- $ref: '#/components/schemas/StemmingAlgorithm'
- nullable: true
enable_hnsw:
description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
type: boolean
nullable: true
TokenizerType:
type: string
enum:
- prefix
- whitespace
- word
- multilingual
GeoIndexType:
type: string
enum:
- geo
DatetimeIndexParams:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/DatetimeIndexType'
is_principal:
description: If true - use this key to organize storage of the collection data. This option assumes that this key will be used in majority of filtered requests.
type: boolean
nullable: true
on_disk:
description: 'If true, store the index on disk. Default: false.'
type: boolean
nullable: true
enable_hnsw:
description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
type: boolean
nullable: true
Snowball:
type: string
enum:
- snowball
UuidIndexType:
type: string
enum:
- uuid
TextIndexType:
type: string
enum:
- text
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
DatetimeIndexType:
type: string
enum:
- datetime
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
BoolIndexParams:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/BoolIndexType'
on_disk:
description: 'If true, store the index on disk. Default: false.'
type: boolean
nullable: true
enable_hnsw:
description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
type: boolean
nullable: true
InferenceUsage:
type: object
required:
- models
properties:
models:
type: object
additionalProperties:
$ref: '#/components/schemas/ModelUsage'
KeywordIndexParams:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/KeywordIndexType'
is_tenant:
description: 'If true - used for tenant optimization. Default: false.'
type: boolean
nullable: true
on_disk:
description: 'If true, store the index on disk. Default: false.'
type: boolean
nullable: true
enable_hnsw:
description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
type: boolean
nullable: true
StopwordsSet:
type: object
properties:
languages:
description: Set of languages to use for stopwords. Multiple pre-defined lists of stopwords can be combined.
type: array
items:
$ref: '#/components/schemas/Language'
uniqueItems: true
nullable: true
custom:
description: Custom stopwords set. Will be merged with the languages set.
type: array
items:
type: string
uniqueItems: true
nullable: true
SnowballLanguage:
description: Languages supported by snowball stemmer.
type: string
enum:
- arabic
- armenian
- danish
- dutch
- english
- finnish
- french
- german
- greek
- hungarian
- italian
- norwegian
- portuguese
- romanian
- russian
- spanish
- swedish
- tamil
- turkish
IntegerIndexType:
type: string
enum:
- integer
CreateFieldIndex:
type: object
required:
- field_name
properties:
field_name:
type: string
field_schema:
anyOf:
- $ref: '#/components/schemas/PayloadFieldSchema'
- nullable: true
IntegerIndexParams:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/IntegerIndexType'
lookup:
description: If true - support direct lookups. Default is true.
type: boolean
nullable: true
range:
description: If true - support ranges filters. Default is true.
type: boolean
nullable: true
is_principal:
description: If true - use this key to organize storage of the collection data. This option assumes that this key will be used in majority of filtered requests. Default is false.
type: boolean
nullable: true
on_disk:
description: 'If true, store the index on disk. Default: false. Default is false.'
type: boolean
nullable: true
enable_hnsw:
description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
type: boolean
nullable: true
WriteOrdering:
description: 'Defines write ordering guarantees for collection operations
* `weak` - write operations may be reordered, works faster, default
* `medium` - write operations go through dynamically selected leader, may be inconsistent for a short period of time in case of leader change
* `strong` - Write operations go through the permanent leader, consistent, but may be unavailable if leader is down'
type: string
enum:
- weak
- medium
- strong
UpdateStatus:
description: '`Acknowledged` - Request is saved to WAL and will be process in a queue. `Completed` - Request is completed, changes are actual. `WaitTimeout` - Request is waiting for timeout.'
type: string
enum:
- acknowledged
- completed
- wait_timeout
PayloadFieldSchema:
anyOf:
- $ref: '#/components/schemas/PayloadSchemaType'
- $ref: '#/components/schemas/PayloadSchemaParams'
PayloadSchemaType:
description: All possible names of payload types
type: string
enum:
- keyword
- integer
- float
- geo
- text
- bool
- datetime
- uuid
UpdateResult:
type: object
required:
- status
properties:
operation_id:
description: Sequential number of the operation
type: integer
format: uint64
minimum: 0
nullable: true
status:
$ref: '#/components/schemas/UpdateStatus'
StopwordsInterface:
anyOf:
- $ref: '#/components/schemas/Language'
- $ref: '#/components/schemas/StopwordsSet'
UuidIndexParams:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/UuidIndexType'
is_tenant:
description: If true - used for tenant optimization.
type: boolean
nullable: true
on_disk:
description: 'If true, store the index on disk. Default: false.'
type: boolean
nullable: true
enable_hnsw:
description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
type: boolean
nullable: true
ModelUsage:
type: object
required:
- tokens
properties:
tokens:
type: integer
format: uint64
minimum: 0
FloatIndexParams:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/FloatIndexType'
is_principal:
description: If true - use this key to organize storage of the collection data. This option assumes that this key will be used in majority of filtered requests.
type: boolean
nullable: true
on_disk:
description: 'If true, store the index on disk. Default: false.'
type: boolean
nullable: true
enable_hnsw:
description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
type: boolean
nullable: true
GeoIndexParams:
type: object
required:
- type
properties:
type:
$ref: '#/components/schemas/GeoIndexType'
on_disk:
description: 'If true, store the index on disk. Default: false.'
type: boolean
nullable: true
enable_hnsw:
description: 'Enable HNSW graph building for this payload field. If true, builds additional HNSW links (Need payload_m > 0). Default: true.'
type: boolean
nullable: true
BoolIndexType:
type: string
enum:
- bool
PayloadSchemaParams:
description: Payload type with parameters
anyOf:
- $ref: '#/components/schemas/KeywordIndexParams'
- $ref: '#/components/schemas/IntegerIndexParams'
- $ref: '#/components/schemas/FloatIndexParams'
- $ref: '#/components/schemas/GeoIndexParams'
- $ref: '#/components/schemas/TextIndexParams'
- $ref: '#/components/schemas/BoolIndexParams'
- $ref: '#/components/schemas/DatetimeIndexParams'
- $ref: '#/components/schemas/UuidIndexParams'
Language:
type: string
enum:
- arabic
- azerbaijani
- basque
- bengali
- catalan
- chinese
- danish
- dutch
- english
- finnish
- french
- german
- greek
- hebrew
- hinglish
- hungarian
- indonesian
- italian
- japanese
- kazakh
- nepali
- norwegian
- portuguese
- romanian
- russian
- slovene
- spanish
- swedish
- tajik
- turkish
SnowballParams:
type: object
required:
- language
- type
properties:
type:
$ref: '#/components/schemas/Snowball'
language:
$ref: '#/components/schemas/SnowballLanguage'
StemmingAlgorithm:
description: Different stemming algorithms with their configs.
anyOf:
- $ref: '#/components/schemas/SnowballParams'
FloatIndexType:
type: string
enum:
- float
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/