gRPC API Overview

High-performance gRPC interface for Qdrant vector database with efficient binary protocol and bidirectional streaming support

Introduction

Qdrant provides a native gRPC API for high-performance vector operations. The gRPC interface offers significant performance advantages over REST, particularly for bulk operations and streaming scenarios.

Why gRPC?

gRPC provides several advantages for vector database operations:

Performance

Binary protocol with efficient serialization reduces network overhead by 30-50% compared to JSON

Type Safety

Strongly-typed Protocol Buffer definitions prevent runtime errors

Streaming

Bidirectional streaming enables efficient batch operations

Code Generation

Auto-generate client libraries in 10+ languages from proto files

Protocol Structure

Qdrant’s gRPC API is defined across multiple protocol buffer files:

• qdrant.proto - Main service definition and health checks
• collections_service.proto - Collection management operations
• points_service.proto - Point CRUD and search operations
• collections.proto - Collection configuration messages
• points.proto - Point structure and query messages

Service Endpoints

The main gRPC services available:

Collections Service

service Collections {
  rpc Get(GetCollectionInfoRequest) returns (GetCollectionInfoResponse);
  rpc List(ListCollectionsRequest) returns (ListCollectionsResponse);
  rpc Create(CreateCollection) returns (CollectionOperationResponse);
  rpc Update(UpdateCollection) returns (CollectionOperationResponse);
  rpc Delete(DeleteCollection) returns (CollectionOperationResponse);
  rpc UpdateAliases(ChangeAliases) returns (CollectionOperationResponse);
}

Points Service

service Points {
  rpc Upsert(UpsertPoints) returns (PointsOperationResponse);
  rpc Delete(DeletePoints) returns (PointsOperationResponse);
  rpc Get(GetPoints) returns (GetResponse);
  rpc Search(SearchPoints) returns (SearchResponse);
  rpc Recommend(RecommendPoints) returns (RecommendResponse);
  rpc Query(QueryPoints) returns (QueryResponse);
  rpc Scroll(ScrollPoints) returns (ScrollResponse);
  rpc Count(CountPoints) returns (CountResponse);
}

Connection Setup

Using Python Client

from qdrant_client import QdrantClient

# Connect via gRPC (default port 6334)
client = QdrantClient(
    host="localhost",
    grpc_port=6334,
    prefer_grpc=True
)

Using Go Client

import (
    "google.golang.org/grpc"
    "github.com/qdrant/go-client/qdrant"
)

conn, err := grpc.Dial(
    "localhost:6334",
    grpc.WithInsecure(),
)
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

client := qdrant.NewQdrantClient(conn)

Using Rust Client

use qdrant_client::client::QdrantClient;

let client = QdrantClient::from_url("http://localhost:6334")
    .build()
    .await?;

Authentication

For authenticated gRPC connections, include API key in metadata:

from qdrant_client import QdrantClient

client = QdrantClient(
    url="https://your-cluster.cloud.qdrant.io",
    grpc_port=6334,
    api_key="your-api-key",
    prefer_grpc=True
)

Performance Considerations

Use gRPC for:

• Bulk upsert operations (>1000 points)
• High-throughput search scenarios
• Batch recommendations
• Streaming scroll operations

Benchmarks

Typical performance improvements with gRPC vs REST:

Operation	REST	gRPC	Improvement
Single point upsert	2ms	1.5ms	25% faster
Batch upsert (1000 points)	150ms	85ms	43% faster
Search (top 10)	5ms	3.5ms	30% faster
Scroll (1000 points)	120ms	70ms	42% faster

Error Handling

gRPC uses standard status codes:

• OK (0) - Success
• INVALID_ARGUMENT (3) - Invalid request parameters
• NOT_FOUND (5) - Collection or point not found
• ALREADY_EXISTS (6) - Resource already exists
• RESOURCE_EXHAUSTED (8) - Rate limit exceeded
• FAILED_PRECONDITION (9) - Operation precondition failed
• UNAVAILABLE (14) - Service temporarily unavailable

Consistency Guarantees

Configure read consistency per request:

from qdrant_client.grpc import ReadConsistency, ReadConsistencyType

results = client.search(
    collection_name="my_collection",
    query_vector=[0.1, 0.2, 0.3],
    limit=10,
    read_consistency=ReadConsistency(
        type=ReadConsistencyType.QUORUM
    )
)

Available consistency types:

• ALL - All replicas must respond
• MAJORITY - Majority of replicas
• QUORUM - Half + 1 replicas

Message Size Limits

gRPC has default message size limits:

• Max receive message: 100MB
• Max send message: 100MB

Configure larger limits for bulk operations if needed.

Proto Files Location

Find proto definitions in the Qdrant repository:

git clone https://github.com/qdrant/qdrant.git
cd qdrant/lib/api/src/grpc/proto

Next Steps

Collections

Manage collections via gRPC

Points

Work with points and vectors

Python Client

Official Python client library

Rust Client

Official Rust client library