gRPC API Overview

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

Overview

REST API

gRPC API

Client Libraries

gRPC API Overview

Introduction

Why gRPC?

Performance

Type Safety

Streaming

Code Generation

Protocol Structure

Service Endpoints

Collections Service

Points Service

Connection Setup

Using Python Client

Using Go Client

Using Rust Client

Authentication

Performance Considerations

Benchmarks

Error Handling

Consistency Guarantees

Message Size Limits

Proto Files Location

Next Steps

Collections

Points

Python Client

Rust Client

Build docs developers (and LLMs) love

Overview

REST API

gRPC API

Client Libraries

​Introduction

​Why gRPC?

Performance

Type Safety

Streaming

Code Generation

​Protocol Structure

​Service Endpoints

​Collections Service

​Points Service

​Connection Setup

​Using Python Client

​Using Go Client

​Using Rust Client

​Authentication

​Performance Considerations

​Benchmarks

​Error Handling

​Consistency Guarantees

​Message Size Limits

​Proto Files Location

​Next Steps

Collections

Points

Python Client

Rust Client

Build docs developers (and LLMs) love

Introduction

Why gRPC?

Protocol Structure

Service Endpoints

Collections Service

Points Service

Connection Setup

Using Python Client

Using Go Client

Using Rust Client

Authentication

Performance Considerations

Benchmarks

Error Handling

Consistency Guarantees

Message Size Limits

Proto Files Location

Next Steps