---
title: "gRPC"
description: "The gRPC API is Weaviate's search API, used by the client libraries for high-performance queries."
url: https://docs.weaviate.io/weaviate/api/grpc
---

# gRPC

The gRPC API is Weaviate's search API. The client libraries use it to run searches and aggregations. gRPC is a high-performance, open-source universal RPC framework that is contract-based and can be used in any environment. It is based on HTTP/2 and Protocol Buffers, and is therefore very fast and efficient.

As of Weaviate `v1.23.7`, the gRPC interface is considered stable. The [Python](https://docs.weaviate.io/weaviate/client-libraries/python), [TypeScript](https://docs.weaviate.io/weaviate/client-libraries/typescript), [Java](https://docs.weaviate.io/weaviate/client-libraries/java), and [C#](https://docs.weaviate.io/weaviate/client-libraries/csharp) client libraries use gRPC. The [Go](https://docs.weaviate.io/weaviate/client-libraries/go) client uses gRPC for queries and batch imports.

## Protocol Buffer (Protobuf) definitions

A gRPC interface is defined through its Protocol Buffer, or Protobuf ([read more](https://protobuf.dev/)) definitions.

In the case of Weaviate, the `.proto` files are listed in the Core library's [proto directory](https://github.com/weaviate/weaviate/tree/master/grpc/proto/v1).

This directory contains the following files:

- `weaviate.proto`: The main Protobuf definition file. This file defines the `Weaviate` service, and specifies the RPC methods available in the Weaviate service.
- `batch.proto`: Defines data structures for handling batch object operations. This file is imported by `weaviate.proto`.
- `search_get.proto`: Defines data structures for handling search (get) operations. This file is imported by `weaviate.proto`.
- `base.proto`: Defines base data structures to be used elsewhere. This file is imported by `batch.proto` and `search_get.proto`.

## How to use gRPC

### Server-side

As an example, the snippet below maps `50051` as the host port so that it can be accessed from outside the container. The `50051` port is mapped to the `50051` port inside the container for gRPC calls, and the `8080` port is mapped to the `8080` port inside the container for REST calls.

> [!NOTE]
>
> We suggest using the default port `50051` for gRPC calls. It can be modified through the `GRPC_PORT` [environment variable](https://docs.weaviate.io/deploy/configuration/env-vars). Note that [Weaviate Cloud](https://docs.weaviate.io/go/console?utm_content=api) uses port `443` for gRPC.

```yaml
---
services:
  weaviate:
    # ... Other settings
    ports:
     - "8080:8080"  # REST calls
     - "50051:50051"  # gRPC calls
  # ... Other settings
```

### Client-side

You can use the gRPC interface through the [Python](https://docs.weaviate.io/weaviate/client-libraries/python), [TypeScript](https://docs.weaviate.io/weaviate/client-libraries/typescript), [Java](https://docs.weaviate.io/weaviate/client-libraries/java), and [C#](https://docs.weaviate.io/weaviate/client-libraries/csharp) client libraries. The [Go](https://docs.weaviate.io/weaviate/client-libraries/go) client uses gRPC for queries and batch imports. The [Go client `v5`](https://docs.weaviate.io/weaviate/client-libraries/go/go-v5) sends batch imports over gRPC, and its gRPC search API is experimental.

Alternatively, you can use other tools, such as the `grpcurl` command-line tool, to interact with the gRPC API. Some options include:

- `grpcurl` command-line tool ([GitHub repo](https://github.com/fullstorydev/grpcurl))
- Postman ([How to send a gRPC request with Postman](https://learning.postman.com/docs/sending-requests/grpc/grpc-request-interface/))

## gRPC-Web

> [!NOTE]
>
> **Added in `v1.38.3`**

Browsers cannot speak plain gRPC. To reach the gRPC API from a browser, Weaviate also serves a gRPC-Web interface over ordinary HTTP. It is served under the `/v1/grpc-web/` path prefix on the same port as the REST API (default `8080`), not on the gRPC port, so there is no second port to expose.

The gRPC-Web interface is enabled by default. **[Runtime configuration](https://docs.weaviate.io/deploy/configuration/env-vars/runtime-config) override:** set `grpc_web_enabled` to `false`. Note the snake\_case. This takes effect without a restart.

This setting has no environment variable equivalent. When the interface is disabled, requests to `/v1/grpc-web/` fall through to the REST handler, so other REST endpoints keep working as usual.

The TypeScript [web client](https://docs.weaviate.io/weaviate/client-libraries/typescript/web-client) connects through gRPC-Web. The other client libraries connect over plain gRPC.
