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.
- Use built in tools to work with your data.
- 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:
- Open the WCD console and find the details panel for your cluster.
- Click the
API keys
button. - 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
- Python Client v3
- JS/TS Client v2
- Go
- Java
- Curl
import weaviate
from weaviate.classes.init import Auth
# Connect to Weaviate Cloud
client = weaviate.connect_to_weaviate_cloud(
cluster_url=weaviate_url, # `weaviate_url`: your Weaviate URL
auth_credentials=Auth.api_key(weaviate_key), # `weaviate_key`: your Weaviate API key
)
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
)
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),
});
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)
}
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);
# 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:
- Open the WCD login page in a browser.
- Enter your email address and password to authenticate.
- 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 tool 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 tool 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:
- Go to the WCD login page.
- Click on click the login button.
- Click
Forgot Password
. - Check your email account for a password reset email from WCD.
- 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, 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()
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()
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:
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:
To add a support plan, contact Weaviate sales.