Custom connections

The Python client and the TypeScript client provide helper methods for common connection types. They also provide custom methods for when you need additional connection configuration.

If you are using one of the other clients, the standard connection methods are configurable for all connections.

Python

import weaviate, os
from weaviate.classes.init import Auth
from weaviate.config import AdditionalConfig, Timeout

# Best practice: store your credentials in environment variables
http_host = os.environ["WEAVIATE_HTTP_HOST"]
grpc_host = os.environ["WEAVIATE_GRPC_HOST"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

JavaScript/TypeScript

// Set these environment variables
// WEAVIATE_HTTP_HOST       your Weaviate instance URL
// WEAVIATE_GRPC_HOST   your Weaviate instance GPC URL
// WEAVIATE_API_KEY   your Weaviate instance API key

const client = await weaviate.connectToCustom(
 {
    httpHost: process.env.WEAVIATE_HTTP_HOST,  // URL only, no http prefix
    httpPort: 443,
    grpcHost: process.env.WEAVIATE_GRPC_HOST,
    grpcPort: 443,        // Default is 50051, WCD uses 443
    grpcSecure: true,
    httpSecure: true,
    authCredentials: new weaviate.ApiKey(process.env.WEAVIATE_API_KEY),

Java

// Best practice: store your credentials in environment variables
String httpHost = System.getenv("WEAVIATE_HTTP_HOST");
String grpcHost = System.getenv("WEAVIATE_GRPC_HOST");
String weaviateApiKey = System.getenv("WEAVIATE_API_KEY");
String cohereApiKey = System.getenv("COHERE_API_KEY");

WeaviateClient client =
    WeaviateClient.connectToCustom(config -> config.scheme("https") // Corresponds to http_secure=True and grpc_secure=True
        .httpHost(httpHost)
        .httpPort(443)
        .grpcHost(grpcHost)
        .grpcPort(443)
        .authentication(Authentication.apiKey(weaviateApiKey))
        .setHeaders(Map.of("X-Cohere-Api-Key", cohereApiKey)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources

// Best practice: store your credentials in environment variables
string httpHost = Environment.GetEnvironmentVariable("WEAVIATE_HTTP_HOST");
string grpcHost = Environment.GetEnvironmentVariable("WEAVIATE_GRPC_HOST");
string weaviateApiKey = Environment.GetEnvironmentVariable("WEAVIATE_API_KEY");
string cohereApiKey = Environment.GetEnvironmentVariable("COHERE_API_KEY");

WeaviateClient client = await WeaviateClientBuilder
    .Custom(
        restEndpoint: httpHost,
        restPort: "443",
        grpcEndpoint: grpcHost,
        grpcPort: "443",
        useSsl: true
    )
    .WithCredentials(Auth.ApiKey(weaviateApiKey))
    .WithHeaders(new Dictionary<string, string> { { "X-Cohere-Api-Key", cohereApiKey } })
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);

Environment variables

Environment variables keep sensitive details out of your source code. Your application imports the information to runtime.

Set an environment variable.

In these examples, the environment variable names are in UPPER_CASE.

Bash/Zsh

export WEAVIATE_URL="http://localhost:8080"
export WEAVIATE_API_KEY="sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz"

Windows PowerShell

$Env:WEAVIATE_URL="http://localhost:8080"
$Env:WEAVIATE_API_KEY="sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz"

Windows Command Prompt

set WEAVIATE_URL=http://localhost:8080
set WEAVIATE_API_KEY=sAmPleKEY8FwELJILn0YDRG9gjy4hReqfInz

Import an environment variable.

Python

weaviate_url = os.getenv("WEAVIATE_URL")
weaviate_key = os.getenv("WEAVIATE_API_KEY")

JavaScript/TypeScript

const weaviateUrl = process.env.WEAVIATE_URL;
const weaviateKey = process.env.WEAVIATE_API_KEY;

weaviateUrl := os.Getenv("WEAVIATE_URL")
weaviateKey := os.Getenv("WEAVIATE_API_KEY")

gRPC Timeouts

The Python client v4 and TypeScript client v3 use gRPC. The gRPC protocol is sensitive to network delay. If you encounter connection timeouts, adjust the timeout values for initialization, queries, and insertions.

Python

import weaviate, os
from weaviate.classes.init import Auth
from weaviate.config import AdditionalConfig, Timeout

# Best practice: store your credentials in environment variables
http_host = os.environ["WEAVIATE_HTTP_HOST"]
grpc_host = os.environ["WEAVIATE_GRPC_HOST"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

JavaScript/TypeScript

// Set these environment variables
// WEAVIATE_HTTP_HOST       your Weaviate instance URL
// WEAVIATE_GRPC_HOST   your Weaviate instance GPC URL
// WEAVIATE_API_KEY   your Weaviate instance API key

const client: WeaviateClient = await weaviate.connectToCustom(
  {
   httpHost: process.env.WEAVIATE_HTTP_HOST,  // URL only, no http prefix
   httpPort: 443,
   grpcHost: process.env.WEAVIATE_GRPC_HOST,
   grpcPort: 443,        // Default is 50051, WCD uses 443
   grpcSecure: true,
   httpSecure: true,
   authCredentials: new weaviate.ApiKey(process.env.WEAVIATE_API_KEY),
   timeout: { init: 30, query: 60, insert: 120 } // Values in seconds
  }
)

console.log(client)

Java

// Best practice: store your credentials in environment variables
String httpHost = System.getenv("WEAVIATE_HTTP_HOST");
String grpcHost = System.getenv("WEAVIATE_GRPC_HOST");
String weaviateApiKey = System.getenv("WEAVIATE_API_KEY");
String cohereApiKey = System.getenv("COHERE_API_KEY");

WeaviateClient client =
    WeaviateClient.connectToCustom(config -> config.scheme("https") // Corresponds to http_secure=True and grpc_secure=True
        .httpHost(httpHost)
        .httpPort(443)
        .grpcHost(grpcHost)
        .grpcPort(443)
        .authentication(Authentication.apiKey(weaviateApiKey))
        .setHeaders(Map.of("X-Cohere-Api-Key", cohereApiKey))
        .timeout(30, 60, 120)); // Values in seconds

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources

// Best practice: store your credentials in environment variables
string httpHost = Environment.GetEnvironmentVariable("WEAVIATE_HTTP_HOST");
string grpcHost = Environment.GetEnvironmentVariable("WEAVIATE_GRPC_HOST");
string weaviateApiKey = Environment.GetEnvironmentVariable("WEAVIATE_API_KEY");
string cohereApiKey = Environment.GetEnvironmentVariable("COHERE_API_KEY");

WeaviateClient client = await WeaviateClientBuilder
    .Custom(
        restEndpoint: httpHost,
        restPort: "443",
        grpcEndpoint: grpcHost,
        grpcPort: "443",
        useSsl: true
    )
    .WithCredentials(Auth.ApiKey(weaviateApiKey))
    .WithHeaders(new Dictionary<string, string> { { "X-Cohere-Api-Key", cohereApiKey } })
    .WithInitTimeout(TimeSpan.FromSeconds(30))
    .WithQueryTimeout(TimeSpan.FromSeconds(60))
    .WithInsertTimeout(TimeSpan.FromSeconds(120))
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);

Third party API keys

Integrations that use external APIs often need API keys. To add third party API keys, follow these examples:

Python

import weaviate, os
from weaviate.classes.init import Auth
from weaviate.config import AdditionalConfig, Timeout

# Best practice: store your credentials in environment variables
http_host = os.environ["WEAVIATE_HTTP_HOST"]
grpc_host = os.environ["WEAVIATE_GRPC_HOST"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]
cohere_api_key = os.environ["COHERE_API_KEY"]

client = weaviate.connect_to_custom(
    http_host=http_host,        # Hostname for the HTTP API connection
    http_port=443,              # Default is 80, WCD uses 443
    http_secure=True,           # Whether to use https (secure) for the HTTP API connection
    grpc_host=grpc_host,        # Hostname for the gRPC API connection
    grpc_port=443,              # Default is 50051, WCD uses 443
    grpc_secure=True,           # Whether to use a secure channel for the gRPC API connection
    auth_credentials=Auth.api_key(weaviate_api_key),    # API key for authentication
    headers={"X-Cohere-Api-Key": cohere_api_key},       # Third party API key (e.g. Cohere)

JavaScript/TypeScript

// Set these environment variables
// WEAVIATE_HTTP_HOST       your Weaviate instance URL
// WEAVIATE_GRPC_HOST   your Weaviate instance GPC URL
// WEAVIATE_API_KEY   your Weaviate instance API key

const client = await weaviate.connectToCustom(
 {
    httpHost: process.env.WEAVIATE_HTTP_HOST,  // URL only, no http prefix
    httpPort: 443,
    grpcHost: process.env.WEAVIATE_GRPC_HOST,
    grpcPort: 443,        // Default is 50051, WCD uses 443
    grpcSecure: true,
    httpSecure: true,
    authCredentials: new weaviate.ApiKey(process.env.WEAVIATE_API_KEY),
    headers: {
      'X-Cohere-Api-Key': process.env.COHERE_API_KEY || ''
    }
  })

console.log(client)

Java

// Best practice: store your credentials in environment variables
String httpHost = System.getenv("WEAVIATE_HTTP_HOST");
String grpcHost = System.getenv("WEAVIATE_GRPC_HOST");
String weaviateApiKey = System.getenv("WEAVIATE_API_KEY");
String cohereApiKey = System.getenv("COHERE_API_KEY");

WeaviateClient client =
    WeaviateClient.connectToCustom(config -> config.scheme("https") // Corresponds to http_secure=True and grpc_secure=True
        .httpHost(httpHost)
        .httpPort(443)
        .grpcHost(grpcHost)
        .grpcPort(443)
        .authentication(Authentication.apiKey(weaviateApiKey))
        .setHeaders(Map.of("X-Cohere-Api-Key", cohereApiKey)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources

// Best practice: store your credentials in environment variables
string httpHost = Environment.GetEnvironmentVariable("WEAVIATE_HTTP_HOST");
string grpcHost = Environment.GetEnvironmentVariable("WEAVIATE_GRPC_HOST");
string weaviateApiKey = Environment.GetEnvironmentVariable("WEAVIATE_API_KEY");
string cohereApiKey = Environment.GetEnvironmentVariable("COHERE_API_KEY");

WeaviateClient client = await WeaviateClientBuilder
    .Custom(
        restEndpoint: httpHost,
        restPort: "443",
        grpcEndpoint: grpcHost,
        grpcPort: "443",
        useSsl: true
    )
    .WithCredentials(Auth.ApiKey(weaviateApiKey))
    .WithHeaders(new Dictionary<string, string> { { "X-Cohere-Api-Key", cohereApiKey } })
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);

OIDC authentication

OIDC lets you authenticate to a self-hosted Weaviate instance using a bearer access token issued by your identity provider (Keycloak, Okta, Azure AD, Auth0, etc.). Your application obtains the token from the IdP, then passes it to the Weaviate client and the client attaches it to every request.

For server-side configuration (enabling OIDC on Weaviate), the supported authentication flows (client credentials, resource owner password, hybrid), and how to obtain tokens from your IdP, see the OIDC configuration guide.

The examples below assume you already have a bearer access token. Set the following environment variables before running them:

WEAVIATE_HTTP_HOST: host:port of the Weaviate REST endpoint (e.g., localhost:8080)
WEAVIATE_GRPC_HOST: host:port of the Weaviate gRPC endpoint (e.g., localhost:50051)
WEAVIATE_OIDC_ACCESS_TOKEN: the access token from your IdP
WEAVIATE_OIDC_REFRESH_TOKEN: (optional) refresh token for automatic renewal
WEAVIATE_OIDC_EXPIRES_IN: (optional) token lifetime in seconds

Python

import os
import weaviate
from weaviate.classes.init import Auth

# Connect to a self-hosted Weaviate instance configured with OIDC.
# Obtain the access token from your identity provider before connecting.
client = weaviate.connect_to_custom(
    http_host="localhost",
    http_port=8580,
    http_secure=False,
    grpc_host="localhost",
    grpc_port=50551,
    grpc_secure=False,
    auth_credentials=Auth.bearer_token(
        access_token=os.environ["WEAVIATE_OIDC_ACCESS_TOKEN"],
        refresh_token=os.environ.get("WEAVIATE_OIDC_REFRESH_TOKEN"),
        expires_in=int(os.environ.get("WEAVIATE_OIDC_EXPIRES_IN", "60")),
    ),
)

JavaScript/TypeScript

// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
const client = await weaviate.connectToCustom({
  httpHost: 'localhost',
  httpPort: 8580,
  httpSecure: false,
  grpcHost: 'localhost',
  grpcPort: 50551,
  grpcSecure: false,
  authCredentials: new weaviate.AuthAccessTokenCredentials({
    accessToken: process.env.WEAVIATE_OIDC_ACCESS_TOKEN!,
    refreshToken: process.env.WEAVIATE_OIDC_REFRESH_TOKEN,
    expiresIn: Number(process.env.WEAVIATE_OIDC_EXPIRES_IN ?? 60),
  }),
});

// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
cfg := weaviate.Config{
    Host:   os.Getenv("WEAVIATE_HTTP_HOST"),
    Scheme: "http",
    AuthConfig: auth.BearerToken{
        AccessToken:  os.Getenv("WEAVIATE_OIDC_ACCESS_TOKEN"),
        RefreshToken: os.Getenv("WEAVIATE_OIDC_REFRESH_TOKEN"),
        ExpiresIn:    60,
    },
}
client, err := weaviate.NewClient(cfg)
if err != nil{
    fmt.Println(err)
}

Java

// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
String accessToken = System.getenv("WEAVIATE_OIDC_ACCESS_TOKEN");
String refreshToken = System.getenv("WEAVIATE_OIDC_REFRESH_TOKEN");
long expiresIn = Long.parseLong(
    System.getenv().getOrDefault("WEAVIATE_OIDC_EXPIRES_IN", "60"));

WeaviateClient client = WeaviateClient.connectToCustom(config -> config
    .scheme("http")
    .httpHost("localhost")
    .httpPort(8580)
    .grpcHost("localhost")
    .grpcPort(50551)
    .authentication(Authentication.bearerToken(accessToken, refreshToken, expiresIn)));

System.out.println(client.isReady()); // Should print: `True`

client.close(); // Free up resources

// Connect to a self-hosted Weaviate instance configured with OIDC.
// Obtain the access token from your identity provider before connecting.
var accessToken = Environment.GetEnvironmentVariable("WEAVIATE_OIDC_ACCESS_TOKEN")!;
var refreshToken = Environment.GetEnvironmentVariable("WEAVIATE_OIDC_REFRESH_TOKEN") ?? "";
var expiresIn = int.Parse(Environment.GetEnvironmentVariable("WEAVIATE_OIDC_EXPIRES_IN") ?? "60");

WeaviateClient client = await WeaviateClientBuilder
    .Custom(
        restEndpoint: "localhost",
        restPort: "8580",
        grpcEndpoint: "localhost",
        grpcPort: "50551",
        useSsl: false,
        credentials: Auth.BearerToken(accessToken, expiresIn, refreshToken)
    )
    .BuildAsync();

var isReady = await client.IsReady();
Console.WriteLine(isReady);

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.