Connect to Weaviate Cloud

There are multiple ways to connect to Weaviate Cloud (WCD):

• Connect through the WCD console.

  • Login to manage your clusters, users, and billing.
  • The built-in Query app connects to WCD clusters and external instances.

• Connect with APIs.

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

Connect with an API

The Weaviate client libraries use API keys to authenticate to WCD instances. By default, API keys are enabled for all WCD clusters.

• Serverless clusters have an administrator key and a read-only key.
• Sandbox clusters only have an administrator key.

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, Manage authentication.

Retrieve your API keys

To retrieve your API keys, follow these steps:

1. Open the WCD console and find the details panel for your cluster.

2. Click the API keys button.
3. Copy the key and store it in a safe location.

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 Client v4

import weaviate
from weaviate.auth import AuthApiKey

# Connect to Weaviate Cloud
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
)

Python Client v3

import weaviate
import os

# Instantiate the client with the auth config
client = weaviate.Client(
    url="https://WEAVIATE_INSTANCE_URL",  # Replace with your Weaviate endpoint
    auth_client_secret=weaviate.auth.AuthApiKey(api_key=weaviate_key),  # Replace with your Weaviate instance API key
)

JS/TS Client v2

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

// Instantiate the client with the auth config
const client = weaviate.client({
  scheme: 'https',
  host: 'WEAVIATE_INSTANCE_URL',  // Replace WEAVIATE_INSTANCE_URL with your instance URL
  apiKey: new ApiKey(weaviateKey),
});

Go

package main

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

// Instantiate the client with the auth config
cfg := weaviate.Config{
  Host:"",  // Replace WEAVIATE_INSTANCE_URL with your instance URL
  Scheme: "http",
  AuthConfig: auth.ApiKey{Value: weaviateKey},
  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", "WEAVIATE_INSTANCE_URL");
// Replace WEAVIATE_INSTANCE_URL with your instance URL
WeaviateClient client = WeaviateAuthClient.apiKey(config, weaviateKey);

Curl

# Replace WEAVIATE_INSTANCE_URL with your instance URL

curl https://WEAVIATE_INSTANCE_URL/v1/meta -H "Authorization: Bearer ${WEAVIATE_API_KEY}" | jq

Connect to the WCD console

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

To connect to the console, follow these steps:

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

Connect an instance with the Query app

The built in Query app connects directly to clusters in your WCD organization without any additional authentication.

To connect the Query app to a Weaviate instance that is not part of your WCD organization, provide an API key for the remote instance. Add the API key to the connection Headers at the bottom of the Query app tab.

Troubleshooting

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

Reset your password

To reset your WCD password, follow these steps:

1. Go to the WCD login page.
2. Click on click the login button.
3. Click Forgot Password.
4. Check your email account for a password reset email from WCD.
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 WCD. 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
from weaviate.auth import AuthApiKey
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_wcs(
    cluster_url=URL,
    auth_credentials=AuthApiKey(APIKEY),
    additional_config=AdditionalConfig(timeout=Timeout(init=10)),
)

# Check connection
client.is_ready()

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

Python Client v4

import weaviate
from weaviate.auth import AuthApiKey

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

# Connect to Weaviate Cloud
client = weaviate.connect_to_wcs(
    cluster_url=URL,
    auth_credentials=AuthApiKey(APIKEY),
    skip_init_checks=True,
)

# Check connection
client.is_ready()

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

More resources

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

• Python
• TypeScript/JavaScript
• Go
• Java

Support

For help with Serverless, Enterprise SaaS, 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.