<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://api.qdrant.tech/"><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.
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://api.qdrant.tech/) 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!
## API Documentation
Python Client API Documentation is available at [python-client.qdrant.tech](https://python-client.qdrant.tech/)
## 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)
```
FastEmbed can also utilise GPU for faster embeddings. To enable GPU support, install
```bash
pip install 'qdrant-client[fastembed-gpu]'
```
```python
from qdrant_client import QdrantClient
# Initialize the client
client = QdrantClient(":memory:") # or QdrantClient(path="path/to/db")
client.set_model(client.DEFAULT_EMBEDDING_MODEL, providers=["CUDAExecutionProvider", "CPUExecutionProvider"])
```
> Note: `fastembed-gpu` and `fastembed` are mutually exclusive. You can only install one of them.
>
> If you previously installed `fastembed`, you might need to start from a fresh environment to install `fastembed-gpu`.
## 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.create_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.query_points(
collection_name="my_collection",
query=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.query_points(
collection_name="my_collection",
query=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
import asyncio
import numpy as np
from qdrant_client import AsyncQdrantClient, models
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.query_points(
collection_name="my_collection",
query=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`.
Raw data
{
"_id": null,
"home_page": null,
"name": "qdrant-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "vector, search, neural, matching, client",
"author": "Andrey Vasnetsov",
"author_email": "andrey@qdrant.tech",
"download_url": "https://files.pythonhosted.org/packages/a7/83/ac6746234106a6d737535ce7b434e17998f26bf187ff4a3f114495d6a52c/qdrant_client-1.13.0.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://api.qdrant.tech/\"><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.\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://api.qdrant.tech/) 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## API Documentation\n\nPython Client API Documentation is available at [python-client.qdrant.tech](https://python-client.qdrant.tech/)\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\nFastEmbed can also utilise GPU for faster embeddings. To enable GPU support, install\n```bash\npip install 'qdrant-client[fastembed-gpu]'\n```\n\n```python\nfrom qdrant_client import QdrantClient\n\n# Initialize the client\nclient = QdrantClient(\":memory:\") # or QdrantClient(path=\"path/to/db\")\nclient.set_model(client.DEFAULT_EMBEDDING_MODEL, providers=[\"CUDAExecutionProvider\", \"CPUExecutionProvider\"])\n```\n\n> Note: `fastembed-gpu` and `fastembed` are mutually exclusive. You can only install one of them.\n>\n> If you previously installed `fastembed`, you might need to start from a fresh environment to install `fastembed-gpu`.\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.create_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\n\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.query_points(\n collection_name=\"my_collection\",\n query=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.query_points(\n collection_name=\"my_collection\",\n query=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\nimport asyncio\n\nimport numpy as np\n\nfrom qdrant_client import AsyncQdrantClient, models\n\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.query_points(\n collection_name=\"my_collection\",\n query=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",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Client library for the Qdrant vector search engine",
"version": "1.13.0",
"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": "d42d4424d730b1eaf3318f9cb86681e1c284caafbebfe51b3635411930e3dad0",
"md5": "102fde85f48ec7501640a7156d920903",
"sha256": "63a063d5232618b609f2c438caf6f3afd3bd110dd80d01be20c596e516efab6b"
},
"downloads": -1,
"filename": "qdrant_client-1.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "102fde85f48ec7501640a7156d920903",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 306439,
"upload_time": "2025-01-17T10:11:40",
"upload_time_iso_8601": "2025-01-17T10:11:40.310415Z",
"url": "https://files.pythonhosted.org/packages/d4/2d/4424d730b1eaf3318f9cb86681e1c284caafbebfe51b3635411930e3dad0/qdrant_client-1.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a783ac6746234106a6d737535ce7b434e17998f26bf187ff4a3f114495d6a52c",
"md5": "3c2b7d119aa54317ad3f6c4ba61e7807",
"sha256": "9708e3194081619b38194c99e7c369064e3f3f328d8a8ef1d71a87425a5ddf0c"
},
"downloads": -1,
"filename": "qdrant_client-1.13.0.tar.gz",
"has_sig": false,
"md5_digest": "3c2b7d119aa54317ad3f6c4ba61e7807",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 266109,
"upload_time": "2025-01-17T10:11:42",
"upload_time_iso_8601": "2025-01-17T10:11:42.414305Z",
"url": "https://files.pythonhosted.org/packages/a7/83/ac6746234106a6d737535ce7b434e17998f26bf187ff4a3f114495d6a52c/qdrant_client-1.13.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-17 10:11:42",
"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"
}
JSON
