https://github.com/qdrant/qdrant-client
Python client for Qdrant vector search engine
https://github.com/qdrant/qdrant-client
qdrant vector-database vector-search vector-search-engine
Last synced: 3 months ago
JSON representation
Python client for Qdrant vector search engine
- Host: GitHub
- URL: https://github.com/qdrant/qdrant-client
- Owner: qdrant
- License: apache-2.0
- Created: 2021-02-09T01:33:20.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2025-07-04T10:48:41.000Z (3 months ago)
- Last Synced: 2025-07-04T11:44:09.446Z (3 months ago)
- Topics: qdrant, vector-database, vector-search, vector-search-engine
- Language: Python
- Homepage: https://qdrant.tech
- Size: 5.04 MB
- Stars: 1,017
- Watchers: 7
- Forks: 152
- Open Issues: 111
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Python Client library for the Qdrant vector search engine.
# 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!
## 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
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 both on CPU and GPU.
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, models
# running qdrant in local mode suitable for experiments
client = QdrantClient(":memory:") # or QdrantClient(path="path/to/db") for local mode and persistent storage
model_name = "sentence-transformers/all-MiniLM-L6-v2"
payload = [
{"document": "Qdrant has Langchain integrations", "source": "Langchain-docs", },
{"document": "Qdrant also has Llama Index integrations", "source": "LlamaIndex-docs"},
]
docs = [models.Document(text=data["document"], model=model_name) for data in payload]
ids = [42, 2]
client.create_collection(
"demo_collection",
vectors_config=models.VectorParams(
size=client.get_embedding_size(model_name), distance=models.Distance.COSINE)
)
client.upload_collection(
collection_name="demo_collection",
vectors=docs,
ids=ids,
payload=payload,
)
search_result = client.query_points(
collection_name="demo_collection",
query=models.Document(text="This is a query document", model=model_name)
).points
print(search_result)
```
FastEmbed can also utilise GPU for faster embeddings. To enable GPU support, install
```bash
pip install 'qdrant-client[fastembed-gpu]'
```
In order to set GPU, extend documents from the previous example with `options`.
```python
models.Document(text="To be computed on GPU", model=model_name, options={"cuda": True})
```
> 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="",
)
```
## 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.
Set up hooks with `pre-commit install` before making contributions.