<p align="center">
<img height="100" src="https://github.com/qdrant/qdrant/raw/master/docs/logo.svg" alt="Qdrant">
</p>
<p align="center">
<b>Python Client library for the <a href="https://github.com/qdrant/qdrant">Qdrant</a> vector search engine.</b>
</p>
<p align=center>
<a href="https://pypi.org/project/qdrant-client/"><img src="https://badge.fury.io/py/qdrant-client.svg" alt="PyPI version" height="18"></a>
<a href="https://qdrant.github.io/qdrant/redoc/index.html"><img src="https://img.shields.io/badge/Docs-OpenAPI%203.0-success" alt="OpenAPI Docs"></a>
<a href="https://github.com/qdrant/qdrant-client/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-success" alt="Apache 2.0 License"></a>
<a href="https://qdrant.to/discord"><img src="https://img.shields.io/badge/Discord-Qdrant-5865F2.svg?logo=discord" alt="Discord"></a>
<a href="https://qdrant.to/roadmap"><img src="https://img.shields.io/badge/Roadmap-2023-bc1439.svg" alt="Roadmap 2023"></a>
<a href="https://python-client.qdrant.tech/"><img src="docs/images/api-icon.svg" width="30px"></a>
</p>
# Python Qdrant Client
Client library and SDK for the [Qdrant](https://github.com/qdrant/qdrant) vector search engine. Python Client API Documentation is available [here](https://python-client.qdrant.tech/).
Library contains type definitions for all Qdrant API and allows to make both Sync and Async requests.
Client allows calls for all [Qdrant API methods](https://qdrant.github.io/qdrant/redoc/index.html) directly.
It also provides some additional helper methods for frequently required operations, e.g. initial collection uploading.
See [QuickStart](https://qdrant.tech/documentation/quick-start/#create-collection) for more details!
## Installation
```
pip install qdrant-client
```
## Features
- Type hints for all API methods
- Local mode - use same API without running server
- REST and gRPC support
- Minimal dependencies
- Extensive Test Coverage
## Local mode
<p align="center">
<!--- https://github.com/qdrant/qdrant-client/raw/master -->
<img max-height="180" src="https://github.com/qdrant/qdrant-client/raw/master/docs/images/try-develop-deploy.png" alt="Qdrant">
</p>
Python client allows you to run same code in local mode without running Qdrant server.
Simply initialize client like this:
```python
from qdrant_client import QdrantClient
client = QdrantClient(":memory:")
# or
client = QdrantClient(path="path/to/db") # Persists changes to disk
```
Local mode is useful for development, prototyping and testing.
- You can use it to run tests in your CI/CD pipeline.
- Run it in Colab or Jupyter Notebook, no extra dependencies required. See an [example](https://colab.research.google.com/drive/1Bz8RSVHwnNDaNtDwotfPj0w7AYzsdXZ-?usp=sharing)
- When you need to scale, simply switch to server mode.
## Fast Embeddings + Simpler API
```
pip install qdrant-client[fastembed]
```
FastEmbed is a library for creating fast vector embeddings on CPU. It is based on ONNX Runtime and allows to run inference on CPU with GPU-like performance.
Qdrant Client can use FastEmbed to create embeddings and upload them to Qdrant. This allows to simplify API and make it more intuitive.
```python
from qdrant_client import QdrantClient
# Initialize the client
client = QdrantClient(":memory:") # or QdrantClient(path="path/to/db")
# Prepare your documents, metadata, and IDs
docs = ["Qdrant has Langchain integrations", "Qdrant also has Llama Index integrations"]
metadata = [
{"source": "Langchain-docs"},
{"source": "Linkedin-docs"},
]
ids = [42, 2]
# Use the new add method
client.add(
collection_name="demo_collection",
documents=docs,
metadata=metadata,
ids=ids
)
search_result = client.query(
collection_name="demo_collection",
query_text="This is a query document"
)
print(search_result)
```
## Connect to Qdrant server
To connect to Qdrant server, simply specify host and port:
```python
from qdrant_client import QdrantClient
client = QdrantClient(host="localhost", port=6333)
# or
client = QdrantClient(url="http://localhost:6333")
```
You can run Qdrant server locally with docker:
```bash
docker run -p 6333:6333 qdrant/qdrant:latest
```
See more launch options in [Qdrant repository](https://github.com/qdrant/qdrant#usage).
## Connect to Qdrant cloud
You can register and use [Qdrant Cloud](https://cloud.qdrant.io/) to get a free tier account with 1GB RAM.
Once you have your cluster and API key, you can connect to it like this:
```python
from qdrant_client import QdrantClient
qdrant_client = QdrantClient(
url="https://xxxxxx-xxxxx-xxxxx-xxxx-xxxxxxxxx.us-east.aws.cloud.qdrant.io:6333",
api_key="<your-api-key>",
)
```
## Examples
Create a new collection
```python
from qdrant_client.models import Distance, VectorParams
client.recreate_collection(
collection_name="my_collection",
vectors_config=VectorParams(size=100, distance=Distance.COSINE),
)
```
Insert vectors into a collection
```python
import numpy as np
from qdrant_client.models import PointStruct
vectors = np.random.rand(100, 100)
# NOTE: consider splitting the data into chunks to avoid hitting the server's payload size limit
# or use `upload_collection` or `upload_points` methods which handle this for you
# WARNING: uploading points one-by-one is not recommended due to requests overhead
client.upsert(
collection_name="my_collection",
points=[
PointStruct(
id=idx,
vector=vector.tolist(),
payload={"color": "red", "rand_number": idx % 10}
)
for idx, vector in enumerate(vectors)
]
)
```
Search for similar vectors
```python
query_vector = np.random.rand(100)
hits = client.search(
collection_name="my_collection",
query_vector=query_vector,
limit=5 # Return 5 closest points
)
```
Search for similar vectors with filtering condition
```python
from qdrant_client.models import Filter, FieldCondition, Range
hits = client.search(
collection_name="my_collection",
query_vector=query_vector,
query_filter=Filter(
must=[ # These conditions are required for search results
FieldCondition(
key='rand_number', # Condition based on values of `rand_number` field.
range=Range(
gte=3 # Select only those results where `rand_number` >= 3
)
)
]
),
limit=5 # Return 5 closest points
)
```
See more examples in our [Documentation](https://qdrant.tech/documentation/)!
### gRPC
To enable (typically, much faster) collection uploading with gRPC, use the following initialization:
```python
from qdrant_client import QdrantClient
client = QdrantClient(host="localhost", grpc_port=6334, prefer_grpc=True)
```
## Async client
Starting from version 1.6.1, all python client methods are available in async version.
To use it, just import `AsyncQdrantClient` instead of `QdrantClient`:
```python
from qdrant_client import AsyncQdrantClient, models
import numpy as np
import asyncio
async def main():
# Your async code using QdrantClient might be put here
client = AsyncQdrantClient(url="http://localhost:6333")
await client.create_collection(
collection_name="my_collection",
vectors_config=models.VectorParams(size=10, distance=models.Distance.COSINE),
)
await client.upsert(
collection_name="my_collection",
points=[
models.PointStruct(
id=i,
vector=np.random.rand(10).tolist(),
)
for i in range(100)
],
)
res = await client.search(
collection_name="my_collection",
query_vector=np.random.rand(10).tolist(), # type: ignore
limit=10,
)
print(res)
asyncio.run(main())
```
Both, gRPC and REST API are supported in async mode.
More examples can be found [here](./tests/test_async_qdrant_client.py).
### Development
This project uses git hooks to run code formatters.
Install `pre-commit` with `pip3 install pre-commit` and set up hooks with `pre-commit install`.
> pre-commit requires python>=3.8
Raw data
{
"_id": null,
"home_page": "https://github.com/qdrant/qdrant-client",
"name": "qdrant-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "vector, search, neural, matching, client",
"author": "Andrey Vasnetsov",
"author_email": "andrey@qdrant.tech",
"download_url": "https://files.pythonhosted.org/packages/cb/d8/69578ea44c266cf86aa5f3fa009ef3fc37750db56b1793d7ec84dbab52ba/qdrant_client-1.8.2.tar.gz",
"platform": null,
"description": "\n\n<p align=\"center\">\n <img height=\"100\" src=\"https://github.com/qdrant/qdrant/raw/master/docs/logo.svg\" alt=\"Qdrant\">\n</p>\n\n<p align=\"center\">\n <b>Python Client library for the <a href=\"https://github.com/qdrant/qdrant\">Qdrant</a> vector search engine.</b>\n</p>\n\n\n<p align=center>\n <a href=\"https://pypi.org/project/qdrant-client/\"><img src=\"https://badge.fury.io/py/qdrant-client.svg\" alt=\"PyPI version\" height=\"18\"></a>\n <a href=\"https://qdrant.github.io/qdrant/redoc/index.html\"><img src=\"https://img.shields.io/badge/Docs-OpenAPI%203.0-success\" alt=\"OpenAPI Docs\"></a>\n <a href=\"https://github.com/qdrant/qdrant-client/blob/master/LICENSE\"><img src=\"https://img.shields.io/badge/License-Apache%202.0-success\" alt=\"Apache 2.0 License\"></a>\n <a href=\"https://qdrant.to/discord\"><img src=\"https://img.shields.io/badge/Discord-Qdrant-5865F2.svg?logo=discord\" alt=\"Discord\"></a>\n <a href=\"https://qdrant.to/roadmap\"><img src=\"https://img.shields.io/badge/Roadmap-2023-bc1439.svg\" alt=\"Roadmap 2023\"></a>\n <a href=\"https://python-client.qdrant.tech/\"><img src=\"docs/images/api-icon.svg\" width=\"30px\"></a>\n</p>\n\n# Python Qdrant Client\n\nClient library and SDK for the [Qdrant](https://github.com/qdrant/qdrant) vector search engine. Python Client API Documentation is available [here](https://python-client.qdrant.tech/).\n\nLibrary contains type definitions for all Qdrant API and allows to make both Sync and Async requests.\n\nClient allows calls for all [Qdrant API methods](https://qdrant.github.io/qdrant/redoc/index.html) directly.\nIt also provides some additional helper methods for frequently required operations, e.g. initial collection uploading.\n\nSee [QuickStart](https://qdrant.tech/documentation/quick-start/#create-collection) for more details!\n\n## Installation\n\n```\npip install qdrant-client\n```\n\n## Features\n\n- Type hints for all API methods\n- Local mode - use same API without running server\n- REST and gRPC support\n- Minimal dependencies\n- Extensive Test Coverage\n\n## Local mode\n\n<p align=\"center\">\n <!--- https://github.com/qdrant/qdrant-client/raw/master -->\n <img max-height=\"180\" src=\"https://github.com/qdrant/qdrant-client/raw/master/docs/images/try-develop-deploy.png\" alt=\"Qdrant\">\n</p>\n\nPython client allows you to run same code in local mode without running Qdrant server.\n\nSimply initialize client like this:\n\n```python\nfrom qdrant_client import QdrantClient\n\nclient = QdrantClient(\":memory:\")\n# or\nclient = QdrantClient(path=\"path/to/db\") # Persists changes to disk\n```\n\nLocal mode is useful for development, prototyping and testing.\n\n- You can use it to run tests in your CI/CD pipeline.\n- Run it in Colab or Jupyter Notebook, no extra dependencies required. See an [example](https://colab.research.google.com/drive/1Bz8RSVHwnNDaNtDwotfPj0w7AYzsdXZ-?usp=sharing)\n- When you need to scale, simply switch to server mode.\n\n## Fast Embeddings + Simpler API\n\n```\npip install qdrant-client[fastembed]\n```\n\nFastEmbed is a library for creating fast vector embeddings on CPU. It is based on ONNX Runtime and allows to run inference on CPU with GPU-like performance.\n\nQdrant Client can use FastEmbed to create embeddings and upload them to Qdrant. This allows to simplify API and make it more intuitive.\n\n```python\nfrom qdrant_client import QdrantClient\n\n# Initialize the client\nclient = QdrantClient(\":memory:\") # or QdrantClient(path=\"path/to/db\")\n\n# Prepare your documents, metadata, and IDs\ndocs = [\"Qdrant has Langchain integrations\", \"Qdrant also has Llama Index integrations\"]\nmetadata = [\n {\"source\": \"Langchain-docs\"},\n {\"source\": \"Linkedin-docs\"},\n]\nids = [42, 2]\n\n# Use the new add method\nclient.add(\n collection_name=\"demo_collection\",\n documents=docs,\n metadata=metadata,\n ids=ids\n)\n\nsearch_result = client.query(\n collection_name=\"demo_collection\",\n query_text=\"This is a query document\"\n)\nprint(search_result)\n```\n\n## Connect to Qdrant server\n\nTo connect to Qdrant server, simply specify host and port:\n\n```python\nfrom qdrant_client import QdrantClient\n\nclient = QdrantClient(host=\"localhost\", port=6333)\n# or\nclient = QdrantClient(url=\"http://localhost:6333\")\n```\n\nYou can run Qdrant server locally with docker:\n\n```bash\ndocker run -p 6333:6333 qdrant/qdrant:latest\n```\n\nSee more launch options in [Qdrant repository](https://github.com/qdrant/qdrant#usage).\n\n\n## Connect to Qdrant cloud\n\nYou can register and use [Qdrant Cloud](https://cloud.qdrant.io/) to get a free tier account with 1GB RAM.\n\nOnce you have your cluster and API key, you can connect to it like this:\n\n```python\nfrom qdrant_client import QdrantClient\n\nqdrant_client = QdrantClient(\n url=\"https://xxxxxx-xxxxx-xxxxx-xxxx-xxxxxxxxx.us-east.aws.cloud.qdrant.io:6333\",\n api_key=\"<your-api-key>\",\n)\n```\n\n## Examples\n\n\nCreate a new collection\n```python\nfrom qdrant_client.models import Distance, VectorParams\n\nclient.recreate_collection(\n collection_name=\"my_collection\",\n vectors_config=VectorParams(size=100, distance=Distance.COSINE),\n)\n```\n\nInsert vectors into a collection\n\n```python\nimport numpy as np\nfrom qdrant_client.models import PointStruct\n\nvectors = np.random.rand(100, 100)\n# NOTE: consider splitting the data into chunks to avoid hitting the server's payload size limit\n# or use `upload_collection` or `upload_points` methods which handle this for you\n# WARNING: uploading points one-by-one is not recommended due to requests overhead\nclient.upsert(\n collection_name=\"my_collection\",\n points=[\n PointStruct(\n id=idx,\n vector=vector.tolist(),\n payload={\"color\": \"red\", \"rand_number\": idx % 10}\n )\n for idx, vector in enumerate(vectors)\n ]\n)\n```\n\nSearch for similar vectors\n\n```python\nquery_vector = np.random.rand(100)\nhits = client.search(\n collection_name=\"my_collection\",\n query_vector=query_vector,\n limit=5 # Return 5 closest points\n)\n```\n\nSearch for similar vectors with filtering condition\n\n```python\nfrom qdrant_client.models import Filter, FieldCondition, Range\n\nhits = client.search(\n collection_name=\"my_collection\",\n query_vector=query_vector,\n query_filter=Filter(\n must=[ # These conditions are required for search results\n FieldCondition(\n key='rand_number', # Condition based on values of `rand_number` field.\n range=Range(\n gte=3 # Select only those results where `rand_number` >= 3\n )\n )\n ]\n ),\n limit=5 # Return 5 closest points\n)\n```\n\nSee more examples in our [Documentation](https://qdrant.tech/documentation/)!\n\n### gRPC\n\nTo enable (typically, much faster) collection uploading with gRPC, use the following initialization:\n\n```python\nfrom qdrant_client import QdrantClient\n\nclient = QdrantClient(host=\"localhost\", grpc_port=6334, prefer_grpc=True)\n```\n\n\n## Async client\n\nStarting from version 1.6.1, all python client methods are available in async version.\n\nTo use it, just import `AsyncQdrantClient` instead of `QdrantClient`:\n\n```python\nfrom qdrant_client import AsyncQdrantClient, models\nimport numpy as np\nimport asyncio\n\nasync def main():\n # Your async code using QdrantClient might be put here\n client = AsyncQdrantClient(url=\"http://localhost:6333\")\n\n await client.create_collection(\n collection_name=\"my_collection\",\n vectors_config=models.VectorParams(size=10, distance=models.Distance.COSINE),\n )\n\n await client.upsert(\n collection_name=\"my_collection\",\n points=[\n models.PointStruct(\n id=i,\n vector=np.random.rand(10).tolist(),\n )\n for i in range(100)\n ],\n )\n\n res = await client.search(\n collection_name=\"my_collection\",\n query_vector=np.random.rand(10).tolist(), # type: ignore\n limit=10,\n )\n\n print(res)\n\nasyncio.run(main())\n```\n\nBoth, gRPC and REST API are supported in async mode.\nMore examples can be found [here](./tests/test_async_qdrant_client.py).\n\n### Development\n\nThis project uses git hooks to run code formatters.\n\nInstall `pre-commit` with `pip3 install pre-commit` and set up hooks with `pre-commit install`.\n\n> pre-commit requires python>=3.8\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Client library for the Qdrant vector search engine",
"version": "1.8.2",
"project_urls": {
"Homepage": "https://github.com/qdrant/qdrant-client",
"Repository": "https://github.com/qdrant/qdrant-client"
},
"split_keywords": [
"vector",
" search",
" neural",
" matching",
" client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cf07b5ad4d11ed64e61aec3f7ab13a5f372b845e0d40363c0da67091c0552b40",
"md5": "457df0d28936d84205bef33f412d0a7a",
"sha256": "ee5341c0486d09e4346b0f5ef7781436e6d8cdbf1d5ecddfde7adb3647d353a8"
},
"downloads": -1,
"filename": "qdrant_client-1.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "457df0d28936d84205bef33f412d0a7a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 223222,
"upload_time": "2024-03-27T14:15:51",
"upload_time_iso_8601": "2024-03-27T14:15:51.771149Z",
"url": "https://files.pythonhosted.org/packages/cf/07/b5ad4d11ed64e61aec3f7ab13a5f372b845e0d40363c0da67091c0552b40/qdrant_client-1.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cbd869578ea44c266cf86aa5f3fa009ef3fc37750db56b1793d7ec84dbab52ba",
"md5": "b4cb979e9d914d247742f0017a4b0b5e",
"sha256": "65078d5328bc0393f42a46a31cd319a989b8285bf3958360acf1dffffdf4cc4e"
},
"downloads": -1,
"filename": "qdrant_client-1.8.2.tar.gz",
"has_sig": false,
"md5_digest": "b4cb979e9d914d247742f0017a4b0b5e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 195225,
"upload_time": "2024-03-27T14:15:54",
"upload_time_iso_8601": "2024-03-27T14:15:54.575569Z",
"url": "https://files.pythonhosted.org/packages/cb/d8/69578ea44c266cf86aa5f3fa009ef3fc37750db56b1793d7ec84dbab52ba/qdrant_client-1.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-27 14:15:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "qdrant",
"github_project": "qdrant-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "qdrant-client"
}