Custom connections

The Python Client v4 and the TypeScript Client v3 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.

PythonJavaScript/TypeScriptJavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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"]

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
)

print(client.is_ready())

import weaviate, { WeaviateClient } from 'weaviate-client';

// 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),
  })

console.log(client)

// 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

warning

Do not hard-code API keys or other credentials in your client code. Use environment variables or a similar secure coding technique instead.

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.

BashWindows PowerShellWindows Command Prompt

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

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

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

Import an environment variable.

PythonJavaScript/TypeScriptGo

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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.

PythonJavaScript/TypeScriptJavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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"]

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
    additional_config=AdditionalConfig(
        timeout=Timeout(init=30, query=60, insert=120)  # Values in seconds
    )
)

print(client.is_ready())

import weaviate, { WeaviateClient } from 'weaviate-client';

// 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)

// 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:

PythonJavaScript/TypeScriptJavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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)
)

print(client.is_ready())

import weaviate, { WeaviateClient } from 'weaviate-client';

// 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)

// 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.

warning

Connecting to Weaviate Cloud (WCD) using OIDC is deprecated and should not be used. Please use API key authentication instead.

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

PythonJavaScript/TypeScriptGoJavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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")),
    ),
)

import weaviate, { WeaviateClient } from 'weaviate-client';

// 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)
}

// 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

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.