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.

Python Client v4

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

# Best practice: store your credentials in environment variables
http_host = os.environ["WCD_HTTP_HOST"]
grpc_host = os.environ["WCD_GRPC_HOST"]
weaviate_api_key = os.environ["WCD_DEMO_RO_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())

  API docs

JS/TS Client v3

// Set these environment variables
// WEAVIATE_URL       your Weaviate instance URL
// WEAVIATE_GPC_URL   your Weaviate instance GPC URL
// WEAVIATE_API_KEY   your Weaviate instance API key

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


const client = await weaviate.connectToCustom(
 {
    httpHost: process.env.WEAVIATE_URL,  // URL only, no http prefix
    httpPort: 443,
    grpcHost: process.env.WEAVIATE_GPC_URL,
    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)

  API docs

Environment variables

danger

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.

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

JS/TS

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

Go

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

Java

String weaviateUrl = System.getenv("WEAVIATE_URL");
String weaviateKey = System.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 Client v4

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

# Best practice: store your credentials in environment variables
http_host = os.environ["WCD_HTTP_HOST"]
grpc_host = os.environ["WCD_GRPC_HOST"]
weaviate_api_key = os.environ["WCD_DEMO_RO_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())

  API docs

JS/TS Client v3

// Set these environment variables
// WEAVIATE_URL       your Weaviate instance URL
// WEAVIATE_API_KEY   your Weaviate instance API key

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

const client: WeaviateClient = await weaviate.connectToCustom(
  process.env.WEAVIATE_URL,
  {
   httpHost: process.env.WEAVIATE_URL,  // URL only, no http prefix
   httpPort: 443,
   grpcHost: process.env.WEAVIATE_GPC_URL,
   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)

  API docs

OIDC authentication

For details on authentication with OpenID Connect (OIDC), see OIDC configuration.

Python Client v4

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

# Best practice: store your credentials in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_username = os.environ["WCD_USERNAME"]
weaviate_password = os.environ["WCD_PASSWORD"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,   # Replace with your Weaviate Cloud URL
    auth_credentials=Auth.client_password(
        username=weaviate_username,  # Your Weaviate Cloud username
        password=weaviate_password   # Your Weaviate Cloud password
    )
)

  API docs

Python Client v3

# Set these environment variables
# WEAVIATE_USER    your Weaviate OIDC username
# WEAVIATE_PWD     your Weaviate OIDC password

import os
import weaviate

resource_owner_config = weaviate.AuthClientPassword(
  username = os.getenv("WEAVIATE_USER"),
  password = os.getenv("WEAVIATE_PWD"),
  )

# Use OIDC credentials to authenticate
client = weaviate.Client("http://localhost:8080", auth_client_secret=resource_owner_config)

  API docs  Deprecated (v3)

JS/TS Client v3

// Set these environment variables
// WEAVIATE_USER    your Weaviate OIDC username
// WEAVIATE_PWD     your Weaviate OIDC password
// WEAVIATE_URL     your Weaviate instance

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

const client = await weaviate.connectToCustom(
 {
    httpHost: process.env.WEAVIATE_URL,  // URL only, no http prefix
    httpPort: 8080,
    grpcHost: process.env.WEAVIATE_GPC_URL,
    grpcPort: 50051,
    grpcSecure: false,
    httpSecure: false,
    authCredentials: new weaviate.AuthUserPasswordCredentials({
     username: process.env.WEAVIATE_USER,
     password: process.env.WEAVIATE_PWD,
    }),
    headers: {
      'X-Cohere-Api-Key': process.env.COHERE_API_KEY || ''
    }
  })

console.log(client)

  API docs

JS/TS Client v2

// Set these environment variables
// WEAVIATE_USER    your Weaviate OIDC username
// WEAVIATE_PWD     your Weaviate OIDC password
// WEAVIATE_URL     your Weaviate instance

import weaviate, { AuthUserPasswordCredentials } from 'weaviate-ts-client';

const client = weaviate.client({
  scheme: "https",
  host: "WEAVIATE_URL",
  authClientSecret: new AuthUserPasswordCredentials({
   username: process.env.WEAVIATE_USER,
   password: process.env.WEAVIATE_PWD,
})
});

console.log(client)

Go

// Set these environment variables
// WEAVIATE_USER    your Weaviate OIDC username
// WEAVIATE_PWD     your Weaviate OIDC password

cfg := weaviate.Config{
    Host:   "weaviate.example.com",
    Scheme: "http",
    AuthConfig: auth.ResourceOwnerPasswordFlow{
        Username: os.Getenv("WEAVIATE_USER"),
        Password: os.Getenv("WEAVIATE_PWD"),
        Scopes:   []string{"offline_access"}, // optional, depends on the configuration of your identity provider (not required with WCD)
    },
    Headers: nil,
}
client, err := weaviate.NewClient(cfg)
if err != nil{
    fmt.Println(err)
}

  API docs

Java

// Set these environment variables
// WEAVIATE_USER    your Weaviate OIDC username
// WEAVIATE_PWD     your Weaviate OIDC password

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;

Config config = new Config("http", "localhost:8080");
WeaviateAuthClient.clientPassword(
config,
System.getenv("WEAVIATE_USER"),
System.getenv("WEAVIATE_PWD"),
Arrays.asList("scope1", "scope2") // optional, depends on the configuration of your identity provider (not required with WCD)
);

  API docs

Questions and feedback

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

• Technical questions
• Documentation feedback