Skip to main content

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:

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

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

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:

import weaviate

client = weaviate.connect_to_local()

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.

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
)

OIDC (WCS username & password)

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:

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

Connect to embedded Weaviate

Embedded instances usually don't need authentication credentials.

import weaviate

client = weaviate.connect_to_embedded()

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.

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:

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
)

Next

For more details, see:

For additional tutorials, see:

Questions and feedback

If you have any questions or feedback, please let us know on our forum. For example, you can: