Skip to main content

How to connect to Weaviate

Overview

Here, you will learn how to connect to your instance of Weaviate, including how to provide authentication parameters such as the Weaviate API key, and inference API keys (e.g. Cohere, Hugging Face or OpenAI API keys).

Prerequisites

For this tutorial, you need to know:

  • The location of your Weaviate instance, and
  • The configuration of the Weaviate instance, especially:
    • Whether authentication is enabled, and if so, the allowed authentication methods.
    • If any modules are being used that use external inference APIs (e.g. OpenAI).

For WCS users

You can find the cluster URL, authentication status and enabled modules for each instance, in the Weaviate Cloud Services dashboard.

For Docker/Kubernetes deployments

You can find the relevant configuration in the configuration files, such as docker-compose.yml for Docker Compose, or values.yaml in the Helm chart.

For Docker instances, your URL will likely be http://localhost:8080 unless specified otherwise.

For Embedded Weaviate

If you are using Embedded Weaviate, you do not need to specify a URL at the client instantiation step, and most likely will not need any authentication.


So, you can simply instantiate with the following.

import weaviate
from weaviate.embedded import EmbeddedOptions

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

For the default configuration, and more about the option in general, see the Embedded Weaviate documentation.

Connecting to Weaviate

Without Authentication

Not recommended

This set up is not recommended in general as anyone can access your Weaviate instance as long as they have the URL.

import weaviate

client = weaviate.Client(
url="https://some-endpoint.weaviate.network", # Replace with your endpoint
)

With authentication enabled

If you do have authentication enabled, you can log in with an API key (recommended), or with OIDC.

This is your Weaviate API key

This is not the place to specify the API key for services such as Cohere, Hugging Face or OpenAI.

import weaviate

# Instantiate the client with the auth config
client = weaviate.Client(
url="https://some-endpoint.weaviate.network", # Replace w/ your endpoint
auth_client_secret=weaviate.AuthApiKey(api_key="YOUR-WEAVIATE-API-KEY"), # Replace w/ your Weaviate instance API key
)

With OIDC authentication (WCS username & password)

Shown setup is for WCS

This authentication method is available for WCS. Your specific identity provider may use a different authentication configuration, of which there are many.

import weaviate

# Instantiate the client with the auth config
client = weaviate.Client(
url="https://some-endpoint.weaviate.network", # Replace w/ your endpoint
auth_client_secret=weaviate.AuthClientPassword(
username = "WCS_USERNAME", # Replace w/ your WCS username
password = "WCS_PASSWORD", # Replace w/ your WCS password
),
)

Providing inference API keys

Additionally, you can provide inference API keys to Weaviate so that you can use modules that leverage external APIs, for example generative-openai or text2vec-cohere.

This is done via an additional header, added as below:

import weaviate

# Instantiate the client with the auth config
client = weaviate.Client(
url="https://some-endpoint.weaviate.network", # Replace w/ your endpoint
auth_client_secret=weaviate.AuthApiKey(api_key="YOUR-WEAVIATE-API-KEY"), # Replace w/ your Weaviate instance API key
additional_headers={
"X-Cohere-Api-Key": "YOUR-COHERE-API-KEY",
"X-HuggingFace-Api-Key": "YOUR-HUGGINGFACE-API-KEY",
"X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY",
},
)

Next

You can read more about some of the concepts discussed here, such as:

For more in-depth tutorials, learn how to build schemas, import data, query data and more.

More Resources

For additional information, try these sources.

  1. Frequently Asked Questions
  2. Weaviate Community Forum
  3. Knowledge base of old issues
  4. Stackoverflow
  5. Weaviate slack channel