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.

Python

import weaviate
from weaviate.embedded import EmbeddedOptions

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

TypeScript

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

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

await client.embedded.start();

// Work with Weaviate

client.embedded.stop();

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.

Python

import weaviate

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

TypeScript

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

const client: WeaviateClient = weaviate.client({
  scheme: 'https',
  host: 'some-endpoint.weaviate.network',  // Replace with your endpoint
});

Go

package main

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

func main() {
    cfg := weaviate.Config{
        Host:   "some-endpoint.weaviate.network",  // Replace with your 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", "some-endpoint.weaviate.network");  // Replace with your endpoint

    WeaviateClient client = new WeaviateClient(config);
  }
}

Curl

curl https://some-endpoint.weaviate.network/v1/meta | jq

With authentication enabled

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

With API key authentication (recommended)

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.

Python

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
)

TypeScript

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

// Instantiate the client with the auth config
const client: WeaviateClient = weaviate.client({
  scheme: 'https',
  host: 'some-endpoint.weaviate.network',
  apiKey: new ApiKey('YOUR-WEAVIATE-API-KEY'),  // Replace w/ your Weaviate instance API key
});

Go

package main

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

// Instantiate the client with the auth config
cfg := weaviate.Config(
  Host:"some-endpoint.weaviate.network",
  Scheme: "http",
  AuthConfig: auth.ApiKey{Value: "YOUR-WEAVIATE-API-KEY"},  // Replace w/ your Weaviate instance API key
  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", "some-endpoint.weaviate.network");
WeaviateClient client = WeaviateAuthClient.apiKey(config, "YOUR-WEAVIATE-API-KEY");  // Replace w/ your Weaviate instance API key

Curl

curl https://some-endpoint.weaviate.network/v1/meta -H "Authorization: Bearer YOUR-WEAVIATE-API-KEY" | jq

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.

• Read more about OIDC authentication.

Python

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

TypeScript

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

const client = weaviate.client({
  scheme: "https",
  host: "some-endpoint.weaviate.network",  // Replace w/ your endpoint
  authClientSecret: new AuthUserPasswordCredentials({
    username: "WCS_USERNAME",  // Replace w/ your WCS username
    password: "WCS_PASSWORD",  // Replace w/ your WCS password
  })
});

Go

package main

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

cfg := weaviate.Config(
  Host:"some-endpoint.weaviate.network",  // Replace w/ your endpoint
  Scheme: "https",
  AuthConfig: auth.ResourceOwnerPasswordFlow{
    Username: "WCS_USERNAME",  // Replace w/ your WCS username
    Password: "WCS_PASSWORD",  // Replace w/ 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", "some-endpoint.weaviate.network");  // Replace w/ your endpoint
WeaviateAuthClient.clientPassword(
    config,
    "WCS_USERNAME",  // Replace w/ your WCS username
    "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:

Python

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

JavaScript

const { default: weaviate } = require('weaviate-ts-client');

// Instantiate the client with the auth config
const client = weaviate.client({
  scheme: 'https',
  host: 'some-endpoint.weaviate.network',
  apiKey: new weaviate.ApiKey('YOUR-WEAVIATE-API-KEY'),  // Replace w/ your Weaviate instance API key
  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',
  },
});

TypeScript

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

// Instantiate the client with the auth config
const client: WeaviateClient = weaviate.client({
  scheme: 'https',
  host: 'some-endpoint.weaviate.network',
  apiKey: new ApiKey('YOUR-WEAVIATE-API-KEY'),  // Replace w/ your Weaviate instance API key
  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',
  },
});

Go

package main

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

// Instantiate the client with the auth config
cfg := weaviate.Config(
  Host:"some-endpoint.weaviate.network",
  Scheme: "http",
  AuthConfig: auth.ApiKey{Value: "YOUR-WEAVIATE-API-KEY"}, // Replace w/ your Weaviate instance API key
  Headers: map[string]string{
    "X-Cohere-Api-Key": "YOUR-COHERE-API-KEY",
    "X-HuggingFace-Api-Key": "YOUR-HUGGINGFACE-API-KEY",
    "X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY",
    },
)

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

Java

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

Map<String, String> headers = new HashMap<String, String>() { {
  put("X-Cohere-Api-Key", "YOUR-COHERE-API-KEY");
  put("X-HuggingFace-Api-Key", "YOUR-HUGGINGFACE-API-KEY");
  put("X-OpenAI-Api-Key", "YOUR-OPENAI-API-KEY");
} };
Config config = new Config("https", "some-endpoint.weaviate.network", headers);
WeaviateClient client = WeaviateAuthClient.apiKey(config, "YOUR-WEAVIATE-API-KEY");  // Replace w/ your Weaviate instance API key

Curl

curl https://some-endpoint.weaviate.network/v1/meta \
-H 'Content-Type: application/json' \
-H "X-Cohere-Api-Key: YOUR-COHERE-API-KEY" \
-H "X-HuggingFace-Api-Key: YOUR-HUGGINGFACE-API-KEY" \
-H "X-OpenAI-Api-Key: YOUR-OPENAI-API-KEY" \
-H "Authorization: Bearer YOUR-WEAVIATE-API-KEY" | jq

Next

If you want to stay focused, continue to the Weaviate, end-to-end tutorial.

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

• Authentication
• Configuration
• Modules

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

More Resources

If you can't find the answer to your question here, please look at the:

1. Frequently Asked Questions. Or,
2. Knowledge base of old issues. Or,
3. For questions: Stackoverflow. Or,
4. For more involved discussion: Weaviate Community Forum. Or,
5. We also have a Slack channel.