Python Client

Qdrant provides a Python client to interact with your Qdrant Database. The client is available on PyPI and can be installed using pip.

Installation

Let’s quickly install the client and get you started.

Installing Python

  • If you don’t have Python installed, you can download it from the official website: https://www.python.org/downloads/

  • Make sure you install Python 3.8 or higher. However, it’s recommended to use the latest version.

Creating a Virtual Environment

It is recommended that a virtual environment be created to install the client. As it will help you manage dependencies and avoid conflicts with other projects.

python3 -m venv qdrant-env # Create a virtual environment
source qdrant-env/bin/activate # Activate the virtual environment

Installing the Python Client

We are going to install the client using pip.

pip install qdrant-client

Using the Qdrant Client

Now that we have installed Python and the qdrant client, let’s see how we can use it.

Importing the Client

from qdrant_client import QdrantClient
from qdrant_client.http.models import Distance, VectorParams
from qdrant_client.http.models import PointStruct
from qdrant_client.http.models import Filter, FieldCondition, MatchValue

These imports will be used to interact with the client in the following examples.

Connecting to the Qdrant Database

To connect to the Qdrant database, you need to create a client object and pass the host and the API-Key to the client.

To get the Host and the API-Key:

  1. Go to TIR and head to the Vector Database section.

  2. There, you will find all your Vector Databases.

  3. Click on the database you want to connect to.

  4. You will find the endpoint host and the API-Key in the Overview tab.

Note

For HTTP (REST) requests, use port no. 6333

For gRPC requests, use port no. 6334

Creating a http client object:

host = <your-qdrant-instance-url>
port = 6333
api_key = <your-api-key>

client = QdrantClient(host=host, port=port, api_key=api_key)

Creating a grpc client object:

host = <your-qdrant-instance-url>
port = 6334
api_key = <your-api-key>

client = QdrantClient(host=host, port=port, api_key=api_key, prefer_grpc=True)

Note

The client object is used to interact with the qdrant instance. Keep the API-Key safe, and do not share it with anyone. The client object will be used in the subsequent examples.

Creating a Collection

Now we will create a collection with the name “example_collection”.

  • We are going to set the vector size to 4. This means that each vector will have 4 dimensions.

  • We are going to set the distance metric to DOT. The distance between vectors will be calculated using the dot product.

  • We are going to set the shard_number to 6. This means that your data will be sharded into 6 individual shards.

  • We are also going to set the replication_factor to 2. This means 2 shard-replicas will be stored, i.e., 1 additional copy of each of your data will be maintained automatically.

For a more detailed explanation of sharding and replication factors, you can refer to the Basic Terminology section.

collection_name = "test_collection"
vectors_config=VectorParams(size=4, distance=Distance.DOT)
shard_number = 6
replication_factor = 2

client.create_collection(collection_name=collection_name,vectors_config=vectors_config,
                        shard_number=shard_number,replication_factor=replication_factor)

Listing Collections

Now, let’s see all the collections that we have created.

collection = client.get_collections()
print(collection)

You may see the following output:

collections=[CollectionDescription(name='test_collection')]

Since we’ve only created one collection, it’s the only one visible. If you create additional collections, you’ll see them as well.

Getting detailed info on a Collection

Now that we have confirmed the collection was created, let’s get the detailed information.

collection_info = client.get_collection(collection_name)
print(collection_info)

Since the output generated is big, we won’t show it here. As a summary, it shows your collection configuration, number of vectors, and more. Feel free to explore it.

Adding Vectors

Now that we have created a collection let’s add some vectors into it. Qdrant allows you to add vectors to the collection using the upsert method. The upsert method takes a list of PointStruct objects as input.

points = [
    PointStruct(id=1, vector=[0.05, 0.61, 0.76, 0.74], payload={"city": "Berlin"}),
    PointStruct(id=2, vector=[0.19, 0.81, 0.75, 0.11], payload={"city": "London"}),
    PointStruct(id=3, vector=[0.36, 0.55, 0.47, 0.94], payload={"city": "Moscow"}),
    PointStruct(id=4, vector=[0.18, 0.01, 0.85, 0.80], payload={"city": "New York"}),
    PointStruct(id=5, vector=[0.24, 0.18, 0.22, 0.44], payload={"city": "Beijing"}),
    PointStruct(id=6, vector=[0.35, 0.08, 0.11, 0.44], payload={"city": "Mumbai"}),
]

client.upsert(collection_name=collection_name, points=points, wait=True)

If the vectors are added successfully, it will return:

UpdateResult(operation_id=<some_id>, status=<UpdateStatus.COMPLETED: 'completed'>)

If there is an error, it will raise an exception. Call the get_collection method to check the number of vectors in the collection.

Searching for Vectors

In production scenarios, you will have a model that generates vectors of your data. You use these vectors to perform similarity search operations in your collection.

Note

TIR provides a service where you can convert your text data into vectors. You can check it out in the GenAI API section on TIR.

Now, let’s perform a vector similarity search.

query_vector = [0.2, 0.1, 0.9, 0.7]
limit = 3

search_result = client.search(collection_name=collection_name,
                              query_vector=query_vector,
                              limit=limit)

print(search_result)

The output should look something like this:

[ScoredPoint(id=4, version=3, score=1.362, payload={'city': 'New York'}, vector=None, shard_key=None), ScoredPoint(id=1, version=3, score=1.273, payload={'city': 'Berlin'}, vector=None, shard_key=None), ScoredPoint(id=3, version=3, score=1.208, payload={'city': 'Moscow'}, vector=None, shard_key=None)]

Deleting the collection

Now that we have played around with the collection, it’s time to delete it.

client.delete_collection(collection_name)

If the collection is deleted successfully, it will return True. If there is an error, it will raise an exception.

Closing the connection

It’s always a good practice to close the connection after you are done with the client.

client.close()

This will close the connection to the qdrant instance.

What’s Next?

This was a quick start guide to get you started with the Qdrant Python client.