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 guide below applies to clusters that have RBAC (Role-Based Access Control) enabled. New clusters with Weaviate version v1.30 (or later) have RBAC enabled by default.

Connecting with API keys when RBAC is disabled

The Weaviate client libraries use API keys to authenticate to Weaviate Cloud instances. If RBAC is disabled, two API keys are created by default. Both Serverless and Sandbox clusters have these 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.

Retrieve your API key and REST endpoint

When connecting to a Weaviate Cloud cluster, you need an API key and the REST endpoint URL for authentication.

If you don't have an existing API key, you'll need to create one. Follow these steps to find the API keys section and create a new key if necessary:

1. Open the Weaviate Cloud console and select your cluster.
2. Navigate to the API Keys section, found in the Cluster details panel.
3. If you need a new API key, click the Create API key button (1 in the image below).

Navigate to the API Keys section.

4. In the Create API Key form, provide a descriptive name for your key (1).
5. Choose the role for this API key (2). You can either select an existing role like admin or viewer, or create a new role with specific permissions.
6. Click the Create button (3).

Create a new API key.

7. Important: This is the only time your API key will be displayed. Make sure to copy it (1) or download it (2) and store it in a secure location immediately after creation. You will not be able to retrieve the full key again.

Save your API key.

This is how you can retrieve your REST Endpoint:

8. On the Cluster details page or within the API Keys section, find the REST Endpoint URL.
9. Copy the REST Endpoint URL and store it securely.

Grab the REST Endpoint URL.

REST Endpoint vs gRPC Endpoint

When using an official Weaviate client library, you need to authenticate using the REST Endpoint and your API key. The client will infer the gRPC endpoint automatically and use the more performant gRPC protocol when available.

Environment variables

Do not hard-code your API key and Weaviate URL in your client code. Consider passing them as environment variables or using a similar secure coding technique.

export WEAVIATE_URL="replaceThisWithYourRESTEndpointURL"
export WEAVIATE_API_KEY="replaceThisWithYourAPIKey"

Connection example

To connect, use the REST Endpoint URL and the Admin API key:

Python

quickstart_check_readiness.py

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

# Best practice: store your credentials in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,
    auth_credentials=Auth.api_key(weaviate_api_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 weaviateUrl = process.env.WEAVIATE_URL as string;
const weaviateApiKey = process.env.WEAVIATE_API_KEY as string;

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  weaviateUrl, // Replace with your Weaviate Cloud URL
  {
    authCredentials: new weaviate.ApiKey(weaviateApiKey), // 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
// WEAVIATE_HOSTNAME            your Weaviate instance hostname
// WEAVIATE_API_KEY          your Weaviate instance API key

package main

import (
    "context"
    "fmt"
    "os"

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

func main() {
    cfg := weaviate.Config{
        Host:       os.Getenv("WEAVIATE_HOSTNAME"),
        Scheme:     "https",
        AuthConfig: auth.ApiKey{Value: os.Getenv("WEAVIATE_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

caution

This client uses the hostname parameter (without the https scheme) instead of a complete URL.

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
// WEAVIATE_HOSTNAME     Your Weaviate instance hostname
// WEAVIATE_API_KEY      Your Weaviate instance API key

public class IsReady {
  public static void main(String[] args) throws Exception {
    String host = System.getenv("WEAVIATE_HOSTNAME");
    String apiKey = System.getenv("WEAVIATE_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

caution

This client uses the hostname parameter (without the https scheme) instead of a complete URL.

Curl

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

curl -w "\nResponse code: %{http_code}\n" \
  -H "Authorization: Bearer $WEAVIATE_API_KEY" \
  $WEAVIATE_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("WEAVIATE_URL")
APIKEY = os.getenv("WEAVIATE_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("WEAVIATE_URL")
APIKEY = os.getenv("WEAVIATE_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.