Connect to Weaviate

Learn how to connect to Weaviate.

Configure your connection to provide authentication parameters and API keys for Weaviate and third-party services. Connect with services like Cohere, Hugging Face, and OpenAI to use their models with your data.

Prerequisites

To configure a connection, you need the following information:

• The location of your Weaviate instance
• If authentication is enabled, the allowed authentication methods
• If you are using modules, the API keys and module connection details

Where to find connection details

Weaviate Cloud Services (WCS) If you are using Weaviate Cloud Services (WCS), the dashboard has a "Details" button. Click the button to get the following information:

• The cluster URL
• Authentication type
• API keys, if enabled
• Module details

Docker and Kubernetes If you are using Docker or Kubernetes, your URL will depend on how the container is configured to provide access.

• For Docker Compose, see docker-compose.yml.
• For Kubernetes, see values.yaml in the Helm chart.

Docker instances by default use the http://localhost:8080 address.

Embedded Weaviate If you are using Embedded Weaviate, you do not need to specify a URL when you create the client. Embedded instances usually don't need authentication credentials. For details, see the Embedded Weaviate documentation.

Environment variables

These examples use environment variables to store connection details and sensitive information such as API keys.

To set environment variables, use the following syntax, where WEAVIATE_URL is the environment variable name and http://localhost:8080 is the value:

Bash/Zsh

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

Windows PowerShell

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

Windows Command Prompt

set WEAVIATE_URL=http://localhost:8080

Then, they can be accessed as follows.

This method is more secure than hardcoding sensitive information in your code, which is shown the commented-out examples below as what not to do.

Python

import os

weaviate_url = os.getenv("WEAVIATE_URL")        # Recommended: save to an environment variable
weaviate_key = os.getenv("WEAVIATE_API_KEY")    # Recommended: save to an environment variable

# Uncomment and use these lines if you want to hardcode (not recommended for production)
# weaviate_url = "<your-weaviate-url>"          # Plaintext url
# weaviate_key = "<your-weaviate-apikey>"       # Plaintext key - not safe for deployment

JavaScript/TypeScript

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

// Uncomment and use these lines if you want to hardcode (not recommended for production)
// const weaviateUrl = "<your-weaviate-url>";
// const weaviateKey = "<your-weaviate-apikey>";

Go

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

// Uncomment and use these lines if you want to hardcode (not recommended for production)
// weaviateUrl = "<your-weaviate-url>"
// weaviateKey = "<your-weaviate-apikey>"

Java

String weaviateUrl = System.getenv("WEAVIATE_URL");
String weaviateKey = System.getenv("WEAVIATE_API_KEY");

// Uncomment and use these lines if you want to hardcode (not recommended for production)
// weaviateUrl = "<your-weaviate-url>";
// weaviateKey = "<your-weaviate-apikey>";

Connecting to Weaviate

Without authentication

Use authentication

Do not expose your Weaviate instance to the public internet if authentication is not enabled. If you do not enable authentication, anyone who has the URL can access your Weaviate instance.

To connect to Weaviate without authentication, follow these examples:

Python (v4)

import weaviate

client = weaviate.connect_to_local()

Python (v3)

import weaviate

client = weaviate.Client(
    url="https://WEAVIATE_INSTANCE_URL",  # Replace with your Weaviate endpoint
)

JavaScript/TypeScript

import weaviate from 'weaviate-ts-client';

const client = weaviate.client({
  scheme: 'https',
  host: 'WEAVIATE_INSTANCE_URL',  // Replace with your Weaviate endpoint
});

Go

package main

import (
    "context"
    "fmt"
    "github.com/weaviate/weaviate-go-client/v4/weaviate"
)

func main() {
    cfg := weaviate.Config{
        Host:   "WEAVIATE_INSTANCE_URL",  // Replace with your Weaviate endpoint
        Scheme: "https",
    }

    client, err := weaviate.NewClient(cfg)
    if err != nil {
      panic(err)
    }
}

Java

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;

public class App {
  public static void main(String[] args) {
    Config config = new Config("https", "WEAVIATE_INSTANCE_URL");  // Replace with your Weaviate endpoint

    WeaviateClient client = new WeaviateClient(config);
  }
}

Curl

# Replace WEAVIATE_INSTANCE_URL with your instance URL

curl http://WEAVIATE_INSTANCE_URL/v1/meta | jq

With authentication

If authentication is enabled, use a Weaviate API key or OIDC credentials to connect. For details, see Authentication.

Weaviate API keys

To authenticate with a Weaviate API key, follow these examples. Note they use environment variables to store the API key.

Edit the sample code to use your Weaviate API key. Be sure to use your Weaviate API key and not the API key for a third-party service like Cohere, Hugging Face, or OpenAI.

Python (v4)

Use an API key to connect to WCS.

import weaviate
from weaviate.auth import AuthApiKey

# Connect to a WCS instance
client = weaviate.connect_to_wcs(
    cluster_url=weaviate_url,                    # `weaviate_url`: your Weaviate URL
    auth_credentials=AuthApiKey(weaviate_key),   # `weaviate_key`: your Weaviate API key
)

Use an API key with a custom connection.

import weaviate
from weaviate.auth import AuthApiKey

# Connect to a local Weaviate instance
client = weaviate.connect_to_custom(
    http_host="localhost",
    http_port=8080,
    http_secure=False,
    grpc_host="localhost",
    grpc_port=50051,
    grpc_secure=False,
    auth_credentials=AuthApiKey(weaviate_key),   # `weaviate_key`: your Weaviate API key
)

Python (v3)

import weaviate
import os

# Instantiate the client with the auth config
client = weaviate.Client(
    url="https://WEAVIATE_INSTANCE_URL",  # Replace with your Weaviate endpoint
    auth_client_secret=weaviate.auth.AuthApiKey(api_key=weaviate_key),  # Replace with your Weaviate instance API key
)

JavaScript/TypeScript

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

// Instantiate the client with the auth config
const client = weaviate.client({
  scheme: 'https',
  host: 'WEAVIATE_INSTANCE_URL',  // Replace WEAVIATE_INSTANCE_URL with your instance URL
  apiKey: new ApiKey(weaviateKey),
});

Go

package main

import (
  "context"
  "fmt"
  "os"
  "github.com/weaviate/weaviate-go-client/v4/weaviate"
)

// Instantiate the client with the auth config
cfg := weaviate.Config{
  Host:"",  // Replace WEAVIATE_INSTANCE_URL with your instance URL
  Scheme: "http",
  AuthConfig: auth.ApiKey{Value: weaviateKey},
  Headers: nil,
}

client, err := weaviate.NewClient(cfg)
if err != nil{
  fmt.Println(err)
}

Java

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

Config config = new Config("https", "WEAVIATE_INSTANCE_URL");
// Replace WEAVIATE_INSTANCE_URL with your instance URL
WeaviateClient client = WeaviateAuthClient.apiKey(config, weaviateKey);

Curl

# Replace WEAVIATE_INSTANCE_URL with your instance URL

curl https://WEAVIATE_INSTANCE_URL/v1/meta -H "Authorization: Bearer ${WEAVIATE_API_KEY}" | jq

OIDC

This example shows a typical OIDC configuration. OIDC providers use a variety of authentication configurations. Your identity provider may use a different configuration, but the concepts are the same. For details, see OIDC authentication.

To authenticate with OIDC, follow these examples:

Python (v4)

import weaviate

wcs_username = os.getenv("WCS_USERNAME")    # Recommended: save to an environment variable
wcs_password = os.getenv("WCS_PASSWORD")    # Recommended: save to an environment variable

client = weaviate.connect_to_wcs(
    cluster_url="https://your-wcs-endpoint.weaviate.network",
    auth_credentials=weaviate.AuthClientPassword(
        username=wcs_username,  # `wcs_username`: your WCS username
        password=wcs_password,  # `wcs_password`: your WCS password
    ),
)

Python (v3)

import weaviate

# Instantiate the client with the auth config
client = weaviate.Client(
    url="https://WEAVIATE_INSTANCE_URL",  # Replace with your Weaviate endpoint
    auth_client_secret=weaviate.AuthClientPassword(
        username = wcs_username,  # Replace with your WCS username
        password = wcs_password,  # Replace with your WCS password
    ),
)

JavaScript/TypeScript

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

const client = weaviate.client({
  scheme: "https",
  host: "WEAVIATE_INSTANCE_URL",  // Replace with your Weaviate endpoint
  authClientSecret: new AuthUserPasswordCredentials({
    username: wcsUsername,  // Replace with your WCS username
    password: wcsPassword,  // Replace with your WCS password
  })
});

Go

package main

import (
  "context"
  "fmt"
  "github.com/weaviate/weaviate-go-client/v4/weaviate"
)

cfg := weaviate.Config{
  Host:"WEAVIATE_INSTANCE_URL",  // Replace with your Weaviate endpoint
  Scheme: "https",
  AuthConfig: auth.ResourceOwnerPasswordFlow{
    Username: wcsUsername,  // Replace with your WCS username
    Password: wcsPassword,  // Replace with your WCS password
  }
}

client, err := weaviate.NewClient(cfg)
if err != nil {
  fmt.Println(err)
}

Java

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

Config config = new Config("https", "WEAVIATE_INSTANCE_URL");  // Replace with your Weaviate endpoint
WeaviateAuthClient.clientPassword(
    config,
    wcsUsername,  // Replace with your WCS username
    wcsPassword,  // Replace with your WCS password
);

Connect to embedded Weaviate

Embedded instances usually don't need authentication credentials.

Python (v4)

import weaviate

client = weaviate.connect_to_embedded()

Python (v3)

import weaviate
from weaviate.embedded import EmbeddedOptions

client = weaviate.Client(
  embedded_options=EmbeddedOptions()
)

JavaScript/TypeScript

import weaviate, { EmbeddedOptions } from 'weaviate-ts-embedded';

const client = weaviate.client(new EmbeddedOptions());

await client.embedded.start();

// Work with Weaviate

client.embedded.stop();

Timeouts

For gRPC-enabled clients, you can set timeout values for initialization, queries or insertions independently. If you are experiencing timeouts, adjust these values to suit your use case.

Python (v4)

import weaviate
from weaviate.classes.init import AdditionalConfig, Timeout

client = weaviate.connect_to_local(
    port=8080,
    grpc_port=50051,
    additional_config=AdditionalConfig(
        timeout=Timeout(init=2, query=45, insert=120)  # Values in seconds
    )
)

Third party API keys

Modules that use external APIs often need API keys. The Weaviate clients send these keys as additional headers.

To add third party API keys, follow these examples:

Python (v4)

import weaviate
from weaviate.auth import AuthApiKey

cohere_key = os.getenv("Cohere_API_KEY")    # Recommended: save to an environment variable

client = weaviate.connect_to_wcs(
    cluster_url=weaviate_url,                       # `weaviate_url`: your Weaviate URL
    auth_credentials=AuthApiKey(weaviate_key),      # `weaviate_key`: your Weaviate API key
    headers={"X-Cohere-Api-Key": cohere_key}        # `cohere_key`: your Cohere key
)

Python (v3)

import weaviate
import os

cohere_key = os.getenv("COHERE_API_KEY")    # Recommended: save to an environment variable

# Instantiate the client with the auth config
client = weaviate.Client(
    url="https://WEAVIATE_INSTANCE_URL",  # Replace with your Weaviate endpoint
    auth_client_secret=weaviate.auth.AuthApiKey(api_key=weaviate_key),  # Replace with your Weaviate instance API key
    additional_headers={
        "X-Cohere-Api-Key": cohere_key,
    },
)

JavaScript/TypeScript

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

var cohereKey = process.env.COHERE_API_KEY;    // Recommended: save to an environment variable

// Instantiate the client with the auth config
const client = weaviate.client({
  scheme: 'https',
  host: 'WEAVIATE_INSTANCE_URL',  // Replace WEAVIATE_INSTANCE_URL with your instance URL
  apiKey: new ApiKey(weaviateKey),  // Replace with your Weaviate instance API key
  headers: {
    'X-Cohere-Api-Key': cohereKey,  // Replace with your Cohere API key
  },
});

Go

package main

import (
  "context"
  "fmt"
  "github.com/weaviate/weaviate-go-client/v4/weaviate"
)

cohereKey := os.Getenv("COHERE_API_KEY")    // Recommended: save to an environment variable

// Instantiate the client with the auth config
cfg := weaviate.Config{
  Host:"",  // Replace WEAVIATE_INSTANCE_URL with your instance URL
  Scheme: "http",
  AuthConfig: auth.ApiKey{Value: weaviateKey}, // Replace with your Weaviate instance API key
  Headers: map[string]string{
    "X-Cohere-Api-Key": cohereKey  // Replace with your Cohere API key
  },
}

client, err := weaviate.NewClient(cfg)
if err != nil{
  fmt.Println(err)
}

Java

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

String cohereKey = System.getenv("COHERE_API_KEY");    // Recommended: save to an environment variable

Map<String, String> headers = new HashMap<String, String>() { {
  put("X-Cohere-Api-Key", cohereKey);
} };
Config config = new Config("https", "WEAVIATE_INSTANCE_URL", headers);
// Replace with your instance URL

WeaviateClient client = WeaviateAuthClient.apiKey(config, weaviateKey);  // Replace with your Weaviate instance API key

Curl

# Replace WEAVIATE_INSTANCE_URL with your instance URL

curl https://WEAVIATE_INSTANCE_URL/v1/meta \
-H 'Content-Type: application/json' \
-H "X-Cohere-Api-Key: YOUR-COHERE-API-KEY" \
-H "Authorization: Bearer YOUR-WEAVIATE-API-KEY" | jq

Next

For more details, see:

• Authentication
• Configuration
• Modules

For additional tutorials, see:

• Build schemas
• Import data
• Query data

Questions and feedback

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

• Technical questions
• Documentation feedback