diff --git a/Cargo.lock b/Cargo.lock index 33d513167e..d2010386de 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -254,7 +254,7 @@ checksum = "bb07d2053ccdbe10e2af2995a2f116c1330396493dc1269f6a91d0ae82e19704" [[package]] name = "api" -version = "0.8.1" +version = "0.8.2" dependencies = [ "prost 0.10.1", "prost-types 0.10.1", @@ -2572,7 +2572,7 @@ dependencies = [ [[package]] name = "qdrant" -version = "0.8.1" +version = "0.8.2" dependencies = [ "actix-cors", "actix-web", diff --git a/Cargo.toml b/Cargo.toml index 0ab2ee862a..c7dc35f1f1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "qdrant" -version = "0.8.1" +version = "0.8.2" authors = ["Andrey Vasnetsov "] edition = "2021" doctest = false diff --git a/docs/redoc/default_version.js b/docs/redoc/default_version.js index e47a7d05dd..4c3e4105b9 100644 --- a/docs/redoc/default_version.js +++ b/docs/redoc/default_version.js @@ -1 +1 @@ -const defaultApiVersion = 'v0.8.1'; \ No newline at end of file +const defaultApiVersion = 'v0.8.2'; \ No newline at end of file diff --git a/docs/redoc/index.html b/docs/redoc/index.html index 020de5442a..699804c982 100644 --- a/docs/redoc/index.html +++ b/docs/redoc/index.html @@ -39,6 +39,7 @@
master + v0.8.2 v0.8.1 v0.8.0 v0.7.0 diff --git a/docs/redoc/v0.8.2/openapi.json b/docs/redoc/v0.8.2/openapi.json new file mode 100644 index 0000000000..ea973e439a --- /dev/null +++ b/docs/redoc/v0.8.2/openapi.json @@ -0,0 +1,3325 @@ +{ + "paths": { + "/cluster": { + "get": { + "tags": [ + "cluster" + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/ClusterStatus" + } + } + } + } + } + } + } + } + }, + "/collections": { + "get": { + "tags": [ + "collections" + ], + "summary": "List collections", + "description": "Get list name of all existing collections", + "operationId": "get_collections", + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/CollectionsResponse" + } + } + } + } + } + } + } + } + }, + "/collections/{collection_name}": { + "get": { + "tags": [ + "collections" + ], + "summary": "Collection info", + "description": "Get detailed information about specified existing collection", + "operationId": "get_collection", + "parameters": [ + { + "name": "collection_name", + "in": "path", + "description": "Name of the collection to retrieve", + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/CollectionInfo" + } + } + } + } + } + } + } + }, + "put": { + "tags": [ + "collections" + ], + "summary": "Create collection", + "description": "Create new collection with given parameters", + "operationId": "create_collection", + "requestBody": { + "description": "Parameters of a new collection", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateCollection" + } + } + } + }, + "parameters": [ + { + "name": "collection_name", + "in": "path", + "description": "Name of the new collection", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "timeout", + "in": "query", + "description": "Wait for operation commit timeout in seconds. \nIf timeout is reached - request will return with service error.\n", + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "type": "boolean" + } + } + } + } + } + } + } + }, + "patch": { + "tags": [ + "collections" + ], + "summary": "Update collection parameters", + "description": "Update parameters of the existing collection", + "operationId": "update_collection", + "requestBody": { + "description": "New parameters", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateCollection" + } + } + } + }, + "parameters": [ + { + "name": "collection_name", + "in": "path", + "description": "Name of the collection to update", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "timeout", + "in": "query", + "description": "Wait for operation commit timeout in seconds. \nIf timeout is reached - request will return with service error.\n", + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "type": "boolean" + } + } + } + } + } + } + } + }, + "delete": { + "tags": [ + "collections" + ], + "summary": "Delete collection", + "description": "Drop collection and all associated data", + "operationId": "delete_collection", + "parameters": [ + { + "name": "collection_name", + "in": "path", + "description": "Name of the collection to delete", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "timeout", + "in": "query", + "description": "Wait for operation commit timeout in seconds. \nIf timeout is reached - request will return with service error.\n", + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "type": "boolean" + } + } + } + } + } + } + } + } + }, + "/collections/aliases": { + "post": { + "tags": [ + "collections" + ], + "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. \nIf timeout is reached - request will return with service error.\n", + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "type": "boolean" + } + } + } + } + } + } + } + } + }, + "/collections/{collection_name}/index": { + "put": { + "tags": [ + "collections" + ], + "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" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/UpdateResult" + } + } + } + } + } + } + } + } + }, + "/collections/{collection_name}/index/{field_name}": { + "delete": { + "tags": [ + "collections" + ], + "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" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/UpdateResult" + } + } + } + } + } + } + } + } + }, + "/collections/{collection_name}/points/{id}": { + "get": { + "tags": [ + "points" + ], + "summary": "Get point", + "description": "Retrieve full information of single point by id", + "operationId": "get_point", + "parameters": [ + { + "name": "collection_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": { + "$ref": "#/components/schemas/ExtendedPointId" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/Record" + } + } + } + } + } + } + } + } + }, + "/collections/{collection_name}/points": { + "post": { + "tags": [ + "points" + ], + "summary": "Get points", + "description": "Retrieve multiple points by specified IDs", + "operationId": "get_points", + "requestBody": { + "description": "List of points to retrieve", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PointRequest" + } + } + } + }, + "parameters": [ + { + "name": "collection_name", + "in": "path", + "description": "Name of the collection to retrieve from", + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Record" + } + } + } + } + } + } + } + } + }, + "put": { + "tags": [ + "points" + ], + "summary": "Upsert points", + "description": "Perform insert + updates on points. If point with given ID already exists - it will be overwritten.", + "operationId": "upsert_points", + "requestBody": { + "description": "Operation to perform on points", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PointInsertOperations" + } + } + } + }, + "parameters": [ + { + "name": "collection_name", + "in": "path", + "description": "Name of the collection to update from", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "wait", + "in": "query", + "description": "If true, wait for changes to actually happen", + "required": false, + "schema": { + "type": "boolean" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/UpdateResult" + } + } + } + } + } + } + } + } + }, + "/collections/{collection_name}/points/delete": { + "post": { + "tags": [ + "points" + ], + "summary": "Delete points", + "description": "Delete points", + "operationId": "delete_points", + "requestBody": { + "description": "Operation to perform on points", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PointsSelector" + } + } + } + }, + "parameters": [ + { + "name": "collection_name", + "in": "path", + "description": "Name of the collection to delete from", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "wait", + "in": "query", + "description": "If true, wait for changes to actually happen", + "required": false, + "schema": { + "type": "boolean" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/UpdateResult" + } + } + } + } + } + } + } + } + }, + "/collections/{collection_name}/points/payload": { + "post": { + "tags": [ + "points" + ], + "summary": "Set payload", + "description": "Set payload for points", + "operationId": "set_payload", + "requestBody": { + "description": "Set payload on points", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetPayload" + } + } + } + }, + "parameters": [ + { + "name": "collection_name", + "in": "path", + "description": "Name of the collection to set from", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "wait", + "in": "query", + "description": "If true, wait for changes to actually happen", + "required": false, + "schema": { + "type": "boolean" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/UpdateResult" + } + } + } + } + } + } + } + } + }, + "/collections/{collection_name}/points/payload/delete": { + "post": { + "tags": [ + "points" + ], + "summary": "Delete payload", + "description": "Delete specified key payload for points", + "operationId": "delete_payload", + "requestBody": { + "description": "delete payload on points", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeletePayload" + } + } + } + }, + "parameters": [ + { + "name": "collection_name", + "in": "path", + "description": "Name of the collection to delete from", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "wait", + "in": "query", + "description": "If true, wait for changes to actually happen", + "required": false, + "schema": { + "type": "boolean" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/UpdateResult" + } + } + } + } + } + } + } + } + }, + "/collections/{collection_name}/points/payload/clear": { + "post": { + "tags": [ + "points" + ], + "summary": "Clear payload", + "description": "Remove all payload for specified points", + "operationId": "clear_payload", + "requestBody": { + "description": "clear payload on points", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PointsSelector" + } + } + } + }, + "parameters": [ + { + "name": "collection_name", + "in": "path", + "description": "Name of the collection to clear payload from", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "wait", + "in": "query", + "description": "If true, wait for changes to actually happen", + "required": false, + "schema": { + "type": "boolean" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/UpdateResult" + } + } + } + } + } + } + } + } + }, + "/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" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "$ref": "#/components/schemas/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" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "type": "array", + "items": { + "$ref": "#/components/schemas/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" + } + } + ], + "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": { + "time": { + "type": "number", + "format": "float", + "description": "Time spent to process this request" + }, + "status": { + "type": "string", + "enum": [ + "ok" + ] + }, + "result": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ScoredPoint" + } + } + } + } + } + } + } + } + } + } + }, + "openapi": "3.0.1", + "info": { + "title": "Qdrant 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`, `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 \"vector_size\": 4,\n \"distance\": \"Dot\"\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 \"vectors_count\": 0,\n \"segments_count\": 5,\n \"disk_data_size\": 0,\n \"ram_data_size\": 0,\n \"config\": {\n \"params\": {\n \"vector_size\": 4,\n \"distance\": \"Dot\"\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 \"max_segment_number\": 5,\n \"memmap_threshold\": 50000,\n \"indexing_threshold\": 20000,\n \"flush_interval_sec\": 1\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": "v0.8.2" + }, + "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" + } + ], + "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 + } + } + }, + "CollectionsResponse": { + "type": "object", + "required": [ + "collections" + ], + "properties": { + "collections": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CollectionDescription" + } + } + } + }, + "CollectionDescription": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string" + } + } + }, + "CollectionInfo": { + "description": "Current statistics and configuration of the collection", + "type": "object", + "required": [ + "config", + "disk_data_size", + "optimizer_status", + "payload_schema", + "ram_data_size", + "segments_count", + "status", + "vectors_count" + ], + "properties": { + "status": { + "$ref": "#/components/schemas/CollectionStatus" + }, + "optimizer_status": { + "$ref": "#/components/schemas/OptimizersStatus" + }, + "vectors_count": { + "description": "Number of vectors in collection", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "segments_count": { + "description": "Number of segments in collection", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "disk_data_size": { + "description": "Disk space, used by collection", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "ram_data_size": { + "description": "RAM used by collection", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "config": { + "$ref": "#/components/schemas/CollectionConfig" + }, + "payload_schema": { + "description": "Types of stored payload", + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/PayloadIndexInfo" + } + } + } + }, + "CollectionStatus": { + "description": "Current state of the collection", + "type": "string", + "enum": [ + "green", + "yellow", + "red" + ] + }, + "OptimizersStatus": { + "description": "Current state of the collection", + "oneOf": [ + { + "type": "string", + "enum": [ + "ok" + ] + }, + { + "description": "Something wrong happened with optimizers", + "type": "object", + "required": [ + "error" + ], + "properties": { + "error": { + "type": "string" + } + }, + "additionalProperties": false + } + ] + }, + "CollectionConfig": { + "type": "object", + "required": [ + "hnsw_config", + "optimizer_config", + "params", + "wal_config" + ], + "properties": { + "params": { + "$ref": "#/components/schemas/CollectionParams" + }, + "hnsw_config": { + "$ref": "#/components/schemas/HnswConfig" + }, + "optimizer_config": { + "$ref": "#/components/schemas/OptimizersConfig" + }, + "wal_config": { + "$ref": "#/components/schemas/WalConfig" + } + } + }, + "CollectionParams": { + "type": "object", + "required": [ + "distance", + "vector_size" + ], + "properties": { + "vector_size": { + "description": "Size of a vectors used", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "distance": { + "$ref": "#/components/schemas/Distance" + }, + "shard_number": { + "description": "Number of shards the collection has", + "default": 1, + "type": "integer", + "format": "uint32", + "minimum": 1 + }, + "on_disk_payload": { + "description": "If true - point's payload will not be stored in memory. It will be read from the disk every time it is requested. This setting saves RAM by (slightly) increasing the response time. Note: those payload values that are involved in filtering and are indexed - remain in RAM.", + "default": false, + "type": "boolean" + } + } + }, + "Distance": { + "description": "Type of internal tags, build from payload Distance function types used to compare vectors", + "type": "string", + "enum": [ + "Cosine", + "Euclid", + "Dot" + ] + }, + "HnswConfig": { + "description": "Config of HNSW index", + "type": "object", + "required": [ + "ef_construct", + "full_scan_threshold", + "m" + ], + "properties": { + "m": { + "description": "Number of edges per node in the index graph. Larger the value - more accurate the search, more space required.", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "ef_construct": { + "description": "Number of neighbours to consider during the index building. Larger the value - more accurate the search, more time required to build index.", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "full_scan_threshold": { + "description": "Minimal size (in KiloBytes) of vectors for additional payload-based indexing. If payload chunk is smaller than `full_scan_threshold_kb` additional indexing won't be used - in this case full-scan search should be preferred by query planner and additional indexing is not required. Note: 1Kb = 1 vector of size 256", + "type": "integer", + "format": "uint", + "minimum": 0 + } + } + }, + "OptimizersConfig": { + "type": "object", + "required": [ + "default_segment_number", + "deleted_threshold", + "flush_interval_sec", + "indexing_threshold", + "max_optimization_threads", + "max_segment_size", + "memmap_threshold", + "vacuum_min_vector_number" + ], + "properties": { + "deleted_threshold": { + "description": "The minimal fraction of deleted vectors in a segment, required to perform segment optimization", + "type": "number", + "format": "double" + }, + "vacuum_min_vector_number": { + "description": "The minimal number of vectors in a segment, required to perform segment optimization", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "default_segment_number": { + "description": "Target amount of segments optimizer will try to keep. Real amount of segments may vary depending on multiple parameters: - Amount of stored points - Current write RPS\n\nIt is recommended to select default number of segments as a factor of the number of search threads, so that each segment would be handled evenly by one of the threads If `default_segment_number = 0`, will be automatically selected by the number of available CPUs", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "max_segment_size": { + "description": "Do not create segments larger this size (in KiloBytes). Large segments might require disproportionately long indexation times, therefore it makes sense to limit the size of segments.\n\nIf indexation speed have more priority for your - make this parameter lower. If search speed is more important - make this parameter higher. Note: 1Kb = 1 vector of size 256", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "memmap_threshold": { + "description": "Maximum size (in KiloBytes) of vectors to store in-memory per segment. Segments larger than this threshold will be stored as read-only memmaped file. To enable memmap storage, lower the threshold Note: 1Kb = 1 vector of size 256", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "indexing_threshold": { + "description": "Maximum size (in KiloBytes) of vectors allowed for plain index. Default value based on https://github.com/google-research/google-research/blob/master/scann/docs/algorithms.md Note: 1Kb = 1 vector of size 256", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "flush_interval_sec": { + "description": "Minimum interval between forced flushes.", + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + "max_optimization_threads": { + "description": "Maximum available threads for optimization workers", + "type": "integer", + "format": "uint", + "minimum": 0 + } + } + }, + "WalConfig": { + "type": "object", + "required": [ + "wal_capacity_mb", + "wal_segments_ahead" + ], + "properties": { + "wal_capacity_mb": { + "description": "Size of a single WAL segment in MB", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "wal_segments_ahead": { + "description": "Number of WAL segments to create ahead of actually used ones", + "type": "integer", + "format": "uint", + "minimum": 0 + } + } + }, + "PayloadIndexInfo": { + "description": "Payload field type & index information", + "type": "object", + "required": [ + "data_type" + ], + "properties": { + "data_type": { + "$ref": "#/components/schemas/PayloadSchemaType" + } + } + }, + "PayloadSchemaType": { + "description": "All possible names of payload types", + "type": "string", + "enum": [ + "keyword", + "integer", + "float", + "geo" + ] + }, + "PointRequest": { + "type": "object", + "required": [ + "ids" + ], + "properties": { + "ids": { + "description": "Look for points with ids", + "type": "array", + "items": { + "$ref": "#/components/schemas/ExtendedPointId" + } + }, + "with_payload": { + "description": "Select which payload to return with the response. Default: All", + "anyOf": [ + { + "$ref": "#/components/schemas/WithPayloadInterface" + }, + { + "nullable": true + } + ] + }, + "with_vector": { + "description": "Whether to return the point vector with the result?", + "default": false, + "type": "boolean" + } + } + }, + "ExtendedPointId": { + "description": "Type, used for specifying point ID in user interface", + "anyOf": [ + { + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + { + "type": "string", + "format": "uuid" + } + ] + }, + "WithPayloadInterface": { + "description": "Options for specifying which payload to include or not", + "anyOf": [ + { + "description": "If `true` - return all payload, If `false` - do not return payload", + "type": "boolean" + }, + { + "description": "Specify which fields to return", + "type": "array", + "items": { + "type": "string" + } + }, + { + "$ref": "#/components/schemas/PayloadSelector" + } + ] + }, + "PayloadSelector": { + "description": "Specifies how to treat payload selector", + "anyOf": [ + { + "$ref": "#/components/schemas/PayloadSelectorInclude" + }, + { + "$ref": "#/components/schemas/PayloadSelectorExclude" + } + ] + }, + "PayloadSelectorInclude": { + "type": "object", + "required": [ + "include" + ], + "properties": { + "include": { + "description": "Only include this payload keys", + "type": "array", + "items": { + "type": "string" + } + } + }, + "additionalProperties": false + }, + "PayloadSelectorExclude": { + "type": "object", + "required": [ + "exclude" + ], + "properties": { + "exclude": { + "description": "Exclude this fields from returning payload", + "type": "array", + "items": { + "type": "string" + } + } + }, + "additionalProperties": false + }, + "Record": { + "description": "Point data", + "type": "object", + "required": [ + "id" + ], + "properties": { + "id": { + "$ref": "#/components/schemas/ExtendedPointId" + }, + "payload": { + "description": "Payload - values assigned to the point", + "anyOf": [ + { + "$ref": "#/components/schemas/Payload" + }, + { + "nullable": true + } + ] + }, + "vector": { + "description": "Vector of the point", + "type": "array", + "items": { + "type": "number", + "format": "float" + }, + "nullable": true + } + } + }, + "Payload": { + "type": "object", + "additionalProperties": true + }, + "SearchRequest": { + "description": "Search request. Holds all conditions and parameters for the search of most similar points by vector similarity given the filtering restrictions.", + "type": "object", + "required": [ + "top", + "vector" + ], + "properties": { + "vector": { + "description": "Look for vectors closest to this", + "type": "array", + "items": { + "type": "number", + "format": "float" + } + }, + "filter": { + "description": "Look only for points which satisfies this conditions", + "anyOf": [ + { + "$ref": "#/components/schemas/Filter" + }, + { + "nullable": true + } + ] + }, + "params": { + "description": "Additional search params", + "anyOf": [ + { + "$ref": "#/components/schemas/SearchParams" + }, + { + "nullable": true + } + ] + }, + "top": { + "description": "Max number of result to return", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "with_payload": { + "description": "Select which payload to return with the response. Default: None", + "anyOf": [ + { + "$ref": "#/components/schemas/WithPayloadInterface" + }, + { + "nullable": true + } + ] + }, + "with_vector": { + "description": "Whether to return the point vector with the result?", + "default": false, + "type": "boolean" + }, + "score_threshold": { + "description": "Define a minimal score threshold for the result. If defined, less similar results will not be returned. Score of the returned result might be higher or smaller than the threshold depending on the Distance function used. E.g. for cosine similarity only higher scores will be returned.", + "type": "number", + "format": "float", + "nullable": true + } + } + }, + "Filter": { + "type": "object", + "properties": { + "should": { + "description": "At least one of those conditions should match", + "type": "array", + "items": { + "$ref": "#/components/schemas/Condition" + }, + "nullable": true + }, + "must": { + "description": "All conditions must match", + "type": "array", + "items": { + "$ref": "#/components/schemas/Condition" + }, + "nullable": true + }, + "must_not": { + "description": "All conditions must NOT match", + "type": "array", + "items": { + "$ref": "#/components/schemas/Condition" + }, + "nullable": true + } + }, + "additionalProperties": false + }, + "Condition": { + "anyOf": [ + { + "$ref": "#/components/schemas/FieldCondition" + }, + { + "$ref": "#/components/schemas/IsEmptyCondition" + }, + { + "$ref": "#/components/schemas/HasIdCondition" + }, + { + "$ref": "#/components/schemas/Filter" + } + ] + }, + "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/Range" + }, + { + "nullable": true + } + ] + }, + "geo_bounding_box": { + "description": "Check if points geo location 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 + } + ] + }, + "values_count": { + "description": "Check number of values of the field", + "anyOf": [ + { + "$ref": "#/components/schemas/ValuesCount" + }, + { + "nullable": true + } + ] + } + } + }, + "Match": { + "description": "Match filter request", + "anyOf": [ + { + "$ref": "#/components/schemas/MatchValue" + }, + { + "$ref": "#/components/schemas/MatchKeyword" + }, + { + "$ref": "#/components/schemas/MatchInteger" + } + ] + }, + "MatchValue": { + "type": "object", + "required": [ + "value" + ], + "properties": { + "value": { + "$ref": "#/components/schemas/ValueVariants" + } + } + }, + "ValueVariants": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "integer", + "format": "int64" + }, + { + "type": "boolean" + } + ] + }, + "MatchKeyword": { + "description": "Match by keyword (deprecated)", + "deprecated": true, + "type": "object", + "required": [ + "keyword" + ], + "properties": { + "keyword": { + "description": "Keyword value to match", + "deprecated": true, + "type": "string" + } + } + }, + "MatchInteger": { + "description": "Match filter request (deprecated)", + "deprecated": true, + "type": "object", + "required": [ + "integer" + ], + "properties": { + "integer": { + "description": "Integer value to match", + "deprecated": true, + "type": "integer", + "format": "int64" + } + } + }, + "Range": { + "description": "Range filter request", + "type": "object", + "properties": { + "lt": { + "description": "point.key < range.lt", + "type": "number", + "format": "double", + "nullable": true + }, + "gt": { + "description": "point.key > range.gt", + "type": "number", + "format": "double", + "nullable": true + }, + "gte": { + "description": "point.key >= range.gte", + "type": "number", + "format": "double", + "nullable": true + }, + "lte": { + "description": "point.key <= range.lte", + "type": "number", + "format": "double", + "nullable": true + } + } + }, + "GeoBoundingBox": { + "description": "Geo filter request\n\nMatches coordinates inside the rectangle, described by coordinates of lop-left and bottom-right edges", + "type": "object", + "required": [ + "bottom_right", + "top_left" + ], + "properties": { + "top_left": { + "$ref": "#/components/schemas/GeoPoint" + }, + "bottom_right": { + "$ref": "#/components/schemas/GeoPoint" + } + } + }, + "GeoPoint": { + "description": "Geo point payload schema", + "type": "object", + "required": [ + "lat", + "lon" + ], + "properties": { + "lon": { + "type": "number", + "format": "double" + }, + "lat": { + "type": "number", + "format": "double" + } + } + }, + "GeoRadius": { + "description": "Geo filter request\n\nMatches coordinates inside the circle of `radius` and center with coordinates `center`", + "type": "object", + "required": [ + "center", + "radius" + ], + "properties": { + "center": { + "$ref": "#/components/schemas/GeoPoint" + }, + "radius": { + "description": "Radius of the area in meters", + "type": "number", + "format": "double" + } + } + }, + "ValuesCount": { + "description": "Values count filter request", + "type": "object", + "properties": { + "lt": { + "description": "point.key.length() < values_count.lt", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "gt": { + "description": "point.key.length() > values_count.gt", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "gte": { + "description": "point.key.length() >= values_count.gte", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "lte": { + "description": "point.key.length() <= values_count.lte", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + } + } + }, + "IsEmptyCondition": { + "description": "Select points with empty payload for a specified field", + "type": "object", + "required": [ + "is_empty" + ], + "properties": { + "is_empty": { + "$ref": "#/components/schemas/PayloadField" + } + } + }, + "PayloadField": { + "description": "Payload field", + "type": "object", + "required": [ + "key" + ], + "properties": { + "key": { + "description": "Payload field name", + "type": "string" + } + } + }, + "HasIdCondition": { + "description": "ID-based filtering condition", + "type": "object", + "required": [ + "has_id" + ], + "properties": { + "has_id": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExtendedPointId" + }, + "uniqueItems": true + } + } + }, + "SearchParams": { + "description": "Additional parameters of the search", + "type": "object", + "properties": { + "hnsw_ef": { + "description": "Params relevant to HNSW index /// Size of the beam in a beam-search. Larger the value - more accurate the result, more time required for search.", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + } + } + }, + "ScoredPoint": { + "description": "Search result", + "type": "object", + "required": [ + "id", + "score", + "version" + ], + "properties": { + "id": { + "$ref": "#/components/schemas/ExtendedPointId" + }, + "version": { + "description": "Point version", + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + "score": { + "description": "Points vector distance to the query vector", + "type": "number", + "format": "float" + }, + "payload": { + "description": "Payload - values assigned to the point", + "anyOf": [ + { + "$ref": "#/components/schemas/Payload" + }, + { + "nullable": true + } + ] + }, + "vector": { + "description": "Vector of the point", + "type": "array", + "items": { + "type": "number", + "format": "float" + }, + "nullable": true + } + } + }, + "UpdateResult": { + "type": "object", + "required": [ + "operation_id", + "status" + ], + "properties": { + "operation_id": { + "description": "Sequential number of the operation", + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + "status": { + "$ref": "#/components/schemas/UpdateStatus" + } + } + }, + "UpdateStatus": { + "type": "string", + "enum": [ + "acknowledged", + "completed" + ] + }, + "RecommendRequest": { + "description": "Recommendation request. Provides positive and negative examples of the vectors, which are already stored in the collection.\n\nService should look for the points which are closer to positive examples and at the same time further to negative examples. The concrete way of how to compare negative and positive distances is up to implementation in `segment` crate.", + "type": "object", + "required": [ + "negative", + "positive", + "top" + ], + "properties": { + "positive": { + "description": "Look for vectors closest to those", + "type": "array", + "items": { + "$ref": "#/components/schemas/ExtendedPointId" + } + }, + "negative": { + "description": "Try to avoid vectors like this", + "type": "array", + "items": { + "$ref": "#/components/schemas/ExtendedPointId" + } + }, + "filter": { + "description": "Look only for points which satisfies this conditions", + "anyOf": [ + { + "$ref": "#/components/schemas/Filter" + }, + { + "nullable": true + } + ] + }, + "params": { + "description": "Additional search params", + "anyOf": [ + { + "$ref": "#/components/schemas/SearchParams" + }, + { + "nullable": true + } + ] + }, + "top": { + "description": "Max number of result to return", + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "with_payload": { + "description": "Select which payload to return with the response. Default: None", + "anyOf": [ + { + "$ref": "#/components/schemas/WithPayloadInterface" + }, + { + "nullable": true + } + ] + }, + "with_vector": { + "description": "Whether to return the point vector with the result?", + "default": false, + "type": "boolean" + }, + "score_threshold": { + "description": "Define a minimal score threshold for the result. If defined, less similar results will not be returned. Score of the returned result might be higher or smaller than the threshold depending on the Distance function used. E.g. for cosine similarity only higher scores will be returned.", + "type": "number", + "format": "float", + "nullable": true + } + } + }, + "ScrollRequest": { + "description": "Scroll request - paginate over all points which matches given condition", + "type": "object", + "properties": { + "offset": { + "description": "Start ID to read points from.", + "anyOf": [ + { + "$ref": "#/components/schemas/ExtendedPointId" + }, + { + "nullable": true + } + ] + }, + "limit": { + "description": "Page size. Default: 10", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "filter": { + "description": "Look only for points which satisfies this conditions. If not provided - all points.", + "anyOf": [ + { + "$ref": "#/components/schemas/Filter" + }, + { + "nullable": true + } + ] + }, + "with_payload": { + "description": "Select which payload to return with the response. Default: All", + "anyOf": [ + { + "$ref": "#/components/schemas/WithPayloadInterface" + }, + { + "nullable": true + } + ] + }, + "with_vector": { + "description": "Whether to return the point vector with the result?", + "default": false, + "type": "boolean" + } + } + }, + "ScrollResult": { + "description": "Result of the points read request", + "type": "object", + "required": [ + "points" + ], + "properties": { + "points": { + "description": "List of retrieved points", + "type": "array", + "items": { + "$ref": "#/components/schemas/Record" + } + }, + "next_page_offset": { + "description": "Offset which should be used to retrieve a next page result", + "anyOf": [ + { + "$ref": "#/components/schemas/ExtendedPointId" + }, + { + "nullable": true + } + ] + } + } + }, + "CreateCollection": { + "description": "Operation for creating new collection and (optionally) specify index params", + "type": "object", + "required": [ + "distance", + "vector_size" + ], + "properties": { + "vector_size": { + "type": "integer", + "format": "uint", + "minimum": 0 + }, + "distance": { + "$ref": "#/components/schemas/Distance" + }, + "shard_number": { + "description": "Number of shards in collection. Default is 1 for standalone, otherwise equal to the number of nodes Minimum is 1", + "default": null, + "type": "integer", + "format": "uint32", + "minimum": 0, + "nullable": true + }, + "on_disk_payload": { + "description": "If true - point's payload will not be stored in memory. It will be read from the disk every time it is requested. This setting saves RAM by (slightly) increasing the response time. Note: those payload values that are involved in filtering and are indexed - remain in RAM.", + "default": null, + "type": "boolean", + "nullable": true + }, + "hnsw_config": { + "description": "Custom params for HNSW index. If none - values from service configuration file are used.", + "anyOf": [ + { + "$ref": "#/components/schemas/HnswConfigDiff" + }, + { + "nullable": true + } + ] + }, + "wal_config": { + "description": "Custom params for WAL. If none - values from service configuration file are used.", + "anyOf": [ + { + "$ref": "#/components/schemas/WalConfigDiff" + }, + { + "nullable": true + } + ] + }, + "optimizers_config": { + "description": "Custom params for Optimizers. If none - values from service configuration file are used.", + "anyOf": [ + { + "$ref": "#/components/schemas/OptimizersConfigDiff" + }, + { + "nullable": true + } + ] + } + } + }, + "HnswConfigDiff": { + "type": "object", + "properties": { + "m": { + "description": "Number of edges per node in the index graph. Larger the value - more accurate the search, more space required.", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "ef_construct": { + "description": "Number of neighbours to consider during the index building. Larger the value - more accurate the search, more time required to build index.", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "full_scan_threshold": { + "description": "Minimal size (in KiloBytes) of vectors for additional payload-based indexing. If payload chunk is smaller than `full_scan_threshold_kb` additional indexing won't be used - in this case full-scan search should be preferred by query planner and additional indexing is not required. Note: 1Kb = 1 vector of size 256", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + } + } + }, + "WalConfigDiff": { + "type": "object", + "properties": { + "wal_capacity_mb": { + "description": "Size of a single WAL segment in MB", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "wal_segments_ahead": { + "description": "Number of WAL segments to create ahead of actually used ones", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + } + } + }, + "OptimizersConfigDiff": { + "type": "object", + "properties": { + "deleted_threshold": { + "description": "The minimal fraction of deleted vectors in a segment, required to perform segment optimization", + "type": "number", + "format": "double", + "nullable": true + }, + "vacuum_min_vector_number": { + "description": "The minimal number of vectors in a segment, required to perform segment optimization", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "default_segment_number": { + "description": "Target amount of segments optimizer will try to keep. Real amount of segments may vary depending on multiple parameters: - Amount of stored points - Current write RPS\n\nIt is recommended to select default number of segments as a factor of the number of search threads, so that each segment would be handled evenly by one of the threads If `default_segment_number = 0`, will be automatically selected by the number of available CPUs", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "max_segment_size": { + "description": "Do not create segments larger this size (in KiloBytes). Large segments might require disproportionately long indexation times, therefore it makes sense to limit the size of segments.\n\nIf indexation speed have more priority for your - make this parameter lower. If search speed is more important - make this parameter higher. Note: 1Kb = 1 vector of size 256", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "memmap_threshold": { + "description": "Maximum size (in KiloBytes) of vectors to store in-memory per segment. Segments larger than this threshold will be stored as read-only memmaped file. To enable memmap storage, lower the threshold Note: 1Kb = 1 vector of size 256", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "indexing_threshold": { + "description": "Maximum size (in KiloBytes) of vectors allowed for plain index. Default value based on https://github.com/google-research/google-research/blob/master/scann/docs/algorithms.md Note: 1Kb = 1 vector of size 256", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + }, + "flush_interval_sec": { + "description": "Minimum interval between forced flushes.", + "type": "integer", + "format": "uint64", + "minimum": 0, + "nullable": true + }, + "max_optimization_threads": { + "description": "Maximum available threads for optimization workers", + "type": "integer", + "format": "uint", + "minimum": 0, + "nullable": true + } + } + }, + "UpdateCollection": { + "description": "Operation for updating parameters of the existing collection", + "type": "object", + "properties": { + "optimizers_config": { + "description": "Custom params for Optimizers. If none - values from service configuration file are used. This operation is blocking, it will only proceed ones all current optimizations are complete", + "anyOf": [ + { + "$ref": "#/components/schemas/OptimizersConfigDiff" + }, + { + "nullable": true + } + ] + } + } + }, + "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" + } + } + } + }, + "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" + } + } + }, + "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" + } + } + }, + "DeleteAliasOperation": { + "description": "Delete alias if exists", + "type": "object", + "required": [ + "delete_alias" + ], + "properties": { + "delete_alias": { + "$ref": "#/components/schemas/DeleteAlias" + } + } + }, + "DeleteAlias": { + "description": "Delete alias if exists", + "type": "object", + "required": [ + "alias_name" + ], + "properties": { + "alias_name": { + "type": "string" + } + } + }, + "RenameAliasOperation": { + "description": "Change alias to a new one", + "type": "object", + "required": [ + "rename_alias" + ], + "properties": { + "rename_alias": { + "$ref": "#/components/schemas/RenameAlias" + } + } + }, + "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" + } + } + }, + "CreateFieldIndex": { + "type": "object", + "required": [ + "field_name" + ], + "properties": { + "field_name": { + "type": "string" + }, + "field_type": { + "anyOf": [ + { + "$ref": "#/components/schemas/PayloadSchemaType" + }, + { + "nullable": true + } + ] + } + } + }, + "PointsSelector": { + "anyOf": [ + { + "$ref": "#/components/schemas/PointIdsList" + }, + { + "$ref": "#/components/schemas/FilterSelector" + } + ] + }, + "PointIdsList": { + "type": "object", + "required": [ + "points" + ], + "properties": { + "points": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExtendedPointId" + } + } + } + }, + "FilterSelector": { + "type": "object", + "required": [ + "filter" + ], + "properties": { + "filter": { + "$ref": "#/components/schemas/Filter" + } + } + }, + "PointInsertOperations": { + "oneOf": [ + { + "$ref": "#/components/schemas/PointsBatch" + }, + { + "$ref": "#/components/schemas/PointsList" + } + ] + }, + "PointStruct": { + "type": "object", + "required": [ + "id", + "vector" + ], + "properties": { + "id": { + "$ref": "#/components/schemas/ExtendedPointId" + }, + "vector": { + "description": "Vector", + "type": "array", + "items": { + "type": "number", + "format": "float" + } + }, + "payload": { + "description": "Payload values (optional)", + "anyOf": [ + { + "$ref": "#/components/schemas/Payload" + }, + { + "nullable": true + } + ] + } + } + }, + "Batch": { + "type": "object", + "required": [ + "ids", + "vectors" + ], + "properties": { + "ids": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExtendedPointId" + } + }, + "vectors": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "number", + "format": "float" + } + } + }, + "payloads": { + "type": "array", + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/Payload" + }, + { + "nullable": true + } + ] + }, + "nullable": true + } + } + }, + "PointsBatch": { + "required": [ + "batch" + ], + "properties": { + "batch": { + "$ref": "#/components/schemas/Batch" + } + } + }, + "PointsList": { + "type": "object", + "required": [ + "points" + ], + "properties": { + "points": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PointStruct" + } + } + } + }, + "SetPayload": { + "type": "object", + "required": [ + "payload", + "points" + ], + "properties": { + "payload": { + "$ref": "#/components/schemas/Payload" + }, + "points": { + "description": "Assigns payload to each point in this list", + "type": "array", + "items": { + "$ref": "#/components/schemas/ExtendedPointId" + } + } + } + }, + "DeletePayload": { + "type": "object", + "required": [ + "keys", + "points" + ], + "properties": { + "keys": { + "type": "array", + "items": { + "type": "string" + } + }, + "points": { + "description": "Deletes values from each point in this list", + "type": "array", + "items": { + "$ref": "#/components/schemas/ExtendedPointId" + } + } + } + }, + "ClusterStatus": { + "description": "Information about current cluster status and structure", + "oneOf": [ + { + "type": "object", + "required": [ + "status" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "disabled" + ] + } + } + }, + { + "description": "Description of enabled cluster", + "type": "object", + "required": [ + "peer_id", + "peers", + "raft_info", + "status" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "enabled" + ] + }, + "peer_id": { + "description": "ID of this peer", + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + "peers": { + "description": "Peers composition of the cluster with main information", + "type": "object", + "additionalProperties": { + "$ref": "#/components/schemas/PeerInfo" + } + }, + "raft_info": { + "$ref": "#/components/schemas/RaftInfo" + } + } + } + ] + }, + "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": { + "type": "string", + "enum": [ + "Follower", + "Candidate", + "Leader", + "PreCandidate" + ] + } + } + } +} diff --git a/lib/api/Cargo.toml b/lib/api/Cargo.toml index eb44171360..0fd4b3bc8b 100644 --- a/lib/api/Cargo.toml +++ b/lib/api/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "api" -version = "0.8.1" +version = "0.8.2" edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html