How to Get Started with Qdrant Locally

In this guide, we will walk through the process of setting up Qdrant locally using Docker, creating a collection, loading data, and executing a basic search query with the Python client. By the end of this article, you will have a working instance of Qdrant and be able to perform vector searches.

Prerequisites

Before you begin, ensure that you have Docker installed and running on your system.

Download and Run Qdrant

Start by pulling the latest Qdrant image from Docker Hub. Open your terminal and run the following command:

docker pull qdrant/qdrant

Once the image is downloaded, you can run the Qdrant service using this command:

docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage:z \
    qdrant/qdrant

This command will map port 6333 for the REST API and port 6334 for the GRPC API. Additionally, the data will be stored in the ./qdrant_storage directory on your host machine, ensuring that both the container and the host can access the same data.

You can now access Qdrant via the following endpoints:

• REST API: http://localhost:6333
• Web UI: http://localhost:6333/dashboard
• GRPC API: http://localhost:6334

Initialize the Client

To interact with Qdrant, you’ll need to initialize the Python client. Start a Python environment and run the following code:

from qdrant_client import QdrantClient

client = QdrantClient(url="http://localhost:6333")

Important: By default, Qdrant does not have encryption or authentication enabled. This means that anyone with network access to your machine can access your Qdrant instance. For production usage, please refer to the Qdrant security documentation for best practices on securing your instance.

Create a Collection

Next, you’ll create a collection to store your vector data. In this example, we will call the collection test_collection and use the dot product distance metric for comparing vectors.

from qdrant_client.models import Distance, VectorParams

client.create_collection(
    collection_name="test_collection",
    vectors_config=VectorParams(size=4, distance=Distance.DOT),
)

Add Vectors

Now that we have a collection, let’s add some vectors along with their associated payloads. Payloads allow you to store additional information related to each vector.

from qdrant_client.models import PointStruct

operation_info = client.upsert(
    collection_name="test_collection",
    wait=True,
    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"}),
    ],
)

print(operation_info)

Response:

operation_id=0 status=<UpdateStatus.COMPLETED: 'completed'>

Run a Query

Now let’s run a query to find the stored vectors that are most similar to a given query vector, [0.2, 0.1, 0.9, 0.7].

search_result = client.query_points(
    collection_name="test_collection",
    query=[0.2, 0.1, 0.9, 0.7],
    with_payload=False,
    limit=3
).points

print(search_result)

Response:

[
  {
    "id": 4,
    "version": 0,
    "score": 1.362,
    "payload": null,
    "vector": null
  },
  {
    "id": 1,
    "version": 0,
    "score": 1.273,
    "payload": null,
    "vector": null
  },
  {
    "id": 3,
    "version": 0,
    "score": 1.208,
    "payload": null,
    "vector": null
  }
]

The results are returned in decreasing order of similarity. Note that payload and vector data is omitted by default; you can enable this if needed.

Add a Filter

To narrow down the results, you can filter by payload. For example, let’s find the closest vectors that include the city “London.”

from qdrant_client.models import Filter, FieldCondition, MatchValue

search_result = client.query_points(
    collection_name="test_collection",
    query=[0.2, 0.1, 0.9, 0.7],
    query_filter=Filter(
        must=[FieldCondition(key="city", match=MatchValue(value="London"))]
    ),
    with_payload=True,
    limit=3,
).points

print(search_result)

Response:

[
    {
        "id": 2,
        "version": 0,
        "score": 0.871,
        "payload": {
            "city": "London"
        },
        "vector": null
    }
]

To enhance the speed of filtered searches on real datasets, it’s recommended to create payload indexes.

Conclusion

Congratulations! You have successfully conducted a vector search with Qdrant. You created a collection, loaded vectors into it, and queried the database with a vector of your own, obtaining the closest results along with their similarity scores.