Connect to Weaviate Cloud

Weaviate Cloud (WCD) offers multiple options on how to connect to your cluster:

• Connect with APIs:

  • Use client libraries to connect to a Weaviate Cloud instance.
  • Use a tool, such as cURL, to connect to the REST API.

• Connect through the Weaviate Cloud console:

  • Login to manage your clusters, users, and billing.
  • Use built-in tools to work with your data.

Connect with an API

The Weaviate client libraries use API keys to authenticate to Weaviate Cloud instances. By default, API keys are enabled for all clusters. Both Serverless and Sandbox clusters have two types of keys:

• Admin key: An administrator that enables read-write access to the cluster.
• ReadOnly key: A viewer key that only allows read access to the cluster.

The Weaviate server authenticates every request.

• If you use a Weaviate client library, pass the API key when you instantiate the client connection. After the connection is established, you do not have to pass the API key when you make additional requests.
• If you use a tool like cURL, add your API key to the request header.

For authentication details, see Account management: Authentication.

Retrieve your API keys

To retrieve your API keys, follow these steps:

1. Open the Weaviate Cloud console and select your cluster.
2. On the Cluster details page, find the API keys section.
3. Copy the needed key and store it in a safe location.

Copy the appropriate API key for your cluster.

Environment variables

Do not hard-code your API key in your client code. Consider passing the API key as an environment variable or using a similar secure coding technique.

export WEAVIATE_API_KEY="replaceThisPartWithYourAPIKey"

Connection example

Python

quickstart_check_readiness.py

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

# Best practice: store your credentials in environment variables
wcd_url = os.environ["WCD_URL"]
wcd_api_key = os.environ["WCD_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=wcd_url,                                    # Replace with your Weaviate Cloud URL
    auth_credentials=Auth.api_key(wcd_api_key),             # Replace with your Weaviate Cloud key
)

print(client.is_ready())  # Should print: `True`

client.close()  # Free up resources

  API docs

JS/TS

quickstart_check_readiness.ts

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

// Best practice: store your credentials in environment variables
const wcdUrl = process.env.WCD_URL as string;
const wcdApiKey = process.env.WCD_API_KEY as string;

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  wcdUrl, // Replace with your Weaviate Cloud URL
  {
    authCredentials: new weaviate.ApiKey(wcdApiKey), // Replace with your Weaviate Cloud API key
  }
);

var clientReadiness = await client.isReady();
console.log(clientReadiness); // Should return `true`

client.close(); // Close the client connection

  API docs

Go

quickstart/1_check_readiness/main.go

// Set these environment variables
// WCD_HOSTNAME            your Weaviate instance hostname
// WCD_API_KEY          your Weaviate instance API key

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/weaviate/weaviate-go-client/v4/weaviate"
    "github.com/weaviate/weaviate-go-client/v4/weaviate/auth"
)

func main() {
    cfg := weaviate.Config{
        Host:       os.Getenv("WCD_HOSTNAME"),
        Scheme:     "https",
        AuthConfig: auth.ApiKey{Value: os.Getenv("WCD_API_KEY")},
    }

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

    // Check the connection
    ready, err := client.Misc().ReadyChecker().Do(context.Background())
    if err != nil {
        panic(err)
    }
    fmt.Printf("%v", ready)
}

  API docs

Java

quickstart/IsReady.java

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.WeaviateAuthClient;
import io.weaviate.client.base.Result;

// Set these environment variables
// WCD_HOSTNAME     Your Weaviate instance hostname
// WCD_API_KEY      Your Weaviate instance API key

public class IsReady {
  public static void main(String[] args) throws Exception {
    String host = System.getenv("WCD_HOSTNAME");
    String apiKey = System.getenv("WCD_API_KEY");

    Config config = new Config("https", host);
    WeaviateClient client = WeaviateAuthClient.apiKey(config, apiKey);

    // check the result
    Result<Boolean> result = client.misc().readyChecker().run();
    System.out.println(result.getResult());

  }
}

  API docs

Curl

# Best practice: store your credentials in environment variables
# export WCD_URL="YOUR_INSTANCE_URL"  # Your Weaviate instance URL
# export WCD_API_KEY="YOUR_API_KEY"   # Your Weaviate instance API key

curl -w "\nResponse code: %{http_code}\n" \
  -H "Authorization: Bearer $WCD_API_KEY" \
  $WCD_URL/v1/.well-known/ready

# You should see "Response code: 200" if the instance is ready

Connect to the Weaviate Cloud console

The Weaviate Cloud console uses your email address and password for authentication. You create the password when you create your Weaviate Cloud account.

To connect to the console, follow these steps:

1. Open the Weaviate Cloud login page in a browser.
2. Enter your email address and password to authenticate.
3. Click Login.

Connect an instance with the Query Tool

The built-in Query tool connects directly to clusters in your Weaviate Cloud organization without any additional authentication.

To connect the Query tool to a Weaviate instance that is not part of your Weaviate Cloud organization, provide an API key for the remote instance.

Add the API key to the connection Headers at the bottom of the Query tool tab.

Copy the appropriate API key for your cluster.

Troubleshooting

This section has solutions for some common problems. For additional help, contact support.

Reset your password

To reset your Weaviate Cloud password, follow these steps:

1. Go to the Weaviate Cloud login page.
2. Click on click the login button.
3. Click Forgot Password.
4. Check your email account for a password reset email from Weaviate Cloud.
5. Click the link and follow the instructions to reset your password. The link is only valid for five minutes.

Connection timeouts

The new Python client uses the gRPC protocol to connect to Weaviate Cloud. The gRPC protocol improves query performance, but the protocol is sensitive to network speeds. If you run into timeout errors, increase the connection timeout value in your connection code.

Python Client v4

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

# Set these environment variables
URL = os.getenv("WCD_URL")
APIKEY = os.getenv("WCD_API_KEY")

# Connect to Weaviate Cloud
client = weaviate.connect_to_weaviate_cloud(
    cluster_url=URL,
    auth_credentials=Auth.api_key(APIKEY),
    additional_config=AdditionalConfig(timeout=Timeout(init=10)),
)

# Check connection
client.is_ready()

  API docs

Alternatively, leave the default timeout values, but skip the initial connection checks.

Python Client v4

import weaviate
from weaviate.classes.init import Auth

# Set these environment variables
URL = os.getenv("WCD_URL")
APIKEY = os.getenv("WCD_API_KEY")

# Connect to Weaviate Cloud
client = weaviate.connect_to_weaviate_cloud(
    cluster_url=URL,
    auth_credentials=Auth.api_key(APIKEY),
    skip_init_checks=True,
)

# Check connection
client.is_ready()

  API docs

gRPC health check error

Problem: gRPC returns a health check error after you update a Serverless cluster.

weaviate.exceptions.WeaviateGRPCUnavailableError: gRPC health check could not be completed.

Solution: Verify the cluster URL is correct and update the URL if needed.

When a Serverless cluster is updated, the cluster URL may change slightly. Weaviate Cloud still routes the old URL, so some connections work, however the new gRPC and the old HTTP URLS are different so connections that require gRCP fail.

To check the URLs, open the Weaviate Cloud Console and check the details panel for your cluster. If you prefix Cluster URL with grpc-, the Cluster URL and the Cluster gRPC URL should match.

Compare the Cluster URL with the connection URL in your application. The old URL and the new URL are similar, but the new one may have an extra subdomain such as .c0.region.

If the URLs are different, update your application's connection code to use the new Cluster URL.

Cluster URLs.

More resources

To authenticate with a Weaviate client library, see the following:

• Python
• TypeScript/JavaScript
• Go
• Java

Support

For help with Serverless Cloud, Enterprise Cloud, and Bring Your Own Cloud accounts, contact Weaviate support directly to open a support ticket.

For questions and support from the Weaviate community, try these resources:

• Community forum
• GitHub
• Slack

To add a support plan, contact Weaviate sales.