Quickstart
This Quickstart guide shows you how to get started with Weaviate Cloud Services (WCS).
Create a WCS account
- Go the WCS homepage.
- Click, "Register here".
- Provide an email address and password.
- After you confirm your email address, return to the login page.
- Log in to the WCS console.
Create a Weaviate Cluster
When you log into the WCS web console, the Dashboard tab lists your clusters. There are no clusters when you log in to a new account. WCS has short-term, sandbox clusters and permanent, managed clusters.
To create a cluster, click the 'Create cluster' button on the WCS Dashboard page.
Follow the steps to create a cluster:
Sandbox clusters
To create a sandbox cluster, follow these steps:
- Select the "Free sandbox" tab.
- Give your cluster a name. WCS adds a random suffix to sandbox cluster names to ensure uniqueness.
- Verify that "Enable Authentication?" is set to "Yes".
- Click create.
It takes a minute or two to create the new cluster. When the cluster is ready, WCS displays a check mark (✔️
) next to the cluster name.
The sandbox is free for 14 days. After 14 days, the sandbox expires and all data is deleted.
To retrieve a copy of your sandbox data before it is deleted, use the cursor API.
To preserve your data and upgrade to a paid instance, contact us for help.
Managed clusters
Managed clusters require billing details. WCS prompts you to add billing details if you have not already added them.
To create a managed cluster, follow these steps:
- Select the "Managed cluster" tab.
- Give your cluster a name.
- Select a region.
- Accept the terms and conditions.
- Click create.
It takes a minute or two to create the new cluster. When the cluster is ready, WCS displays a check mark (✔️
) next to the cluster name.
Explore the Details panel
The Details panel lists cluster metrics, authorization details, and other useful information. To access your cluster, you need the cluster URL and authentication details.
To get the cluster URL and authentication details, follow these steps:
- Click the
Details
button to open the Details panel.
- To get the API keys, click the
API keys
button.
- Copy the API key for the
Admin
user to a safe place.
- The cluster URL begins with the cluster name. Copy it to a safe place.
Install a client library
The WCS console includes a query interface, but most most WCS interactions rely on a Weaviate client. Clients are available in several programming languages. Chose one that makes sense for your project.
To install a client, follow these steps for your language:
- Python (v4)
- Python (v3)
- JS/TS (Beta)
- JS/TS
- Go
- Java
Add weaviate-client
to your Python environment with pip
.
Please use the v4
client with Weaviate 1.23.7
or higher.
pip install -U weaviate-client
Add weaviate-client
to your Python environment with pip
:
pip install "weaviate-client==3.*"
Add weaviate-client
to your project with npm
:
npm install weaviate-client --tag beta
Add weaviate-ts-client
to your project with npm
:
npm install weaviate-ts-client
Add weaviate-go-client
to your project with go get
:
go get github.com/weaviate/weaviate-go-client/v4
Add this dependency to your project:
<dependency>
<groupId>io.weaviate</groupId>
<artifactId>client</artifactId>
<version>4.0.0</version> <!-- Check latest version -->
</dependency>
Connect to your WCS instance
These code samples demonstrate how to connect a Weaviate client to your WCS cluster.
To connect to your cluster, follow these steps for your language:
- Copy the sample client code to a file.
- Find your WCS cluster URL and API key in the WCS Console.
- Create environment variables, or edit the sample code, to pass the URL and API keys to your client.
- Run the client code.
- Python (v4)
- Python (v3)
- JS/TS (Beta)
- JS/TS
- Go
- Java
import weaviate
import os
with weaviate.connect_to_wcs(
cluster_url=os.getenv("WCS_DEMO_URL"), # Replace with your WCS URL
auth_credentials=weaviate.auth.AuthApiKey(os.getenv("WCS_DEMO_RO_KEY")), # Replace with your WCS key
headers={'X-OpenAI-Api-key': os.getenv("OPENAI_APIKEY")} # Replace with your vectorizer API key
) as client: # Use this context manager to ensure the connection is closed
print(client.is_ready())
import weaviate
client = weaviate.Client(
url="https://WEAVIATE_INSTANCE_URL/", # Replace with your Weaviate endpoint
auth_client_secret=weaviate.auth.AuthApiKey(api_key="YOUR-WEAVIATE-API-KEY"), # Replace with your Weaviate instance API key
additional_headers={
'X-OpenAI-Api-key': os.getenv("OPENAI_APIKEY") # Replace with your third party API key and identifying header
}
)
print(client.is_ready())
import weaviate, { WeaviateClient } from 'weaviate-client';
const client: WeaviateClient = await weaviate.connectToWCS(
'https://WEAVIATE_INSTANCE_URL', { // Replace with your Weaviate endpoint
authCredentials: new weaviate.ApiKey('YOUR-WEAVIATE-API-KEY'), // Replace with your Weaviate instance API key
});
const response = await client.isReady();
console.log(response);
import weaviate, { WeaviateClient, ObjectsBatcher, ApiKey } from 'weaviate-ts-client';
const client: WeaviateClient = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your Weaviate endpoint
apiKey: new ApiKey('YOUR-WEAVIATE-API-KEY'), // Replace with your Weaviate instance API key
});
const response = await client.misc
.readyChecker()
.do();
console.log(response);
package main
import (
"context"
"fmt"
"github.com/weaviate/weaviate-go-client/v4/weaviate"
)
func main() {
cfg := weaviate.Config{
Host: "WEAVIATE_INSTANCE_URL/", // Replace with your Weaviate endpoint
Scheme: "https",
AuthConfig: auth.ApiKey{Value: "YOUR-WEAVIATE-API-KEY"}, // Replace with your Weaviate instance API key
}
client, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}
isReady, err := client.Misc().ReadyChecker().Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", isReady)
}
package io.weaviate;
import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.misc.model.Meta;
public class App {
public static void main(String[] args) {
Config config = new Config("https", "WEAVIATE_INSTANCE_URL/"); // Replace with your Weaviate endpoint
WeaviateClient client = WeaviateAuthClient.apiKey(config, "YOUR-WEAVIATE-API-KEY"); // Replace with your Weaviate instance API key
Result<Boolean> result = client.misc().readyChecker().run();
if (result.hasErrors()) {
System.out.println(result.getError());
return;
}
System.out.println(result.getResult());
}
}
If you are connected, the server returns True
.
Define a collection
Weaviate stores objects in collections. Every collection has a schema. Collection schemas are highly configurable, but some properties cannot be changed after you create the collection. For best results, define a collection schema before you import your data.
To create a schema for the Question
collection, follow these steps in your client code:
- Create a client connection.
- Add the collection definition code after the client creation code.
- Run the code.
- Python (v4)
- Python (v3)
- JS/TS (Beta)
- JS/TS
- Go
- Curl
questions = client.collections.create(
name="Question",
vectorizer_config=wvc.config.Configure.Vectorizer.text2vec_openai(), # If set to "none" you must always provide vectors yourself. Could be any other "text2vec-*" also.
generative_config=wvc.config.Configure.Generative.openai() # Ensure the `generative-openai` module is used for generative queries
)
class_obj = {
"class": "Question",
"vectorizer": "text2vec-openai", # If set to "none" you must always provide vectors yourself. Could be any other "text2vec-*" also.
"moduleConfig": {
"text2vec-openai": {},
"generative-openai": {} # Ensure the `generative-openai` module is used for generative queries
}
}
client.schema.create_class(class_obj)
const schema = {
name: 'Question',
vectorizer: weaviate.configure.vectorizer.text2VecOpenAI(),
generative: weaviate.configure.generative.openAI(),
}
async function addSchema() {
const newCollection = await client.collections.create(schema)
console.log('We have a new class!', newCollection['name']);
}
await addSchema();
const classObj = {
'class': 'Question',
'vectorizer': 'text2vec-openai', // If set to "none" you must always provide vectors yourself. Could be any other "text2vec-*" also.
'moduleConfig': {
'text2vec-openai': {},
'generative-openai': {} // Ensure the `generative-openai` module is used for generative queries
},
};
async function addSchema() {
const res = await client.schema.classCreator().withClass(classObj).do();
console.log(res);
}
await addSchema();
package main
import (
"context"
"github.com/weaviate/weaviate-go-client/v4/weaviate"
"github.com/weaviate/weaviate-go-client/v4/weaviate/auth"
"github.com/weaviate/weaviate/entities/models"
)
func main() {
cfg := weaviate.Config{
Host: "WEAVIATE_INSTANCE_URL/", // Replace with your Weaviate endpoint
Scheme: "https",
AuthConfig: auth.ApiKey{Value: "YOUR-WEAVIATE-API-KEY"}, // Replace with your Weaviate instance API key
Headers: map[string]string{
"X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY", // Replace with your inference API key
},
}
client, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}
classObj := &models.Class{
Class: "Question",
Vectorizer: "text2vec-openai", // If set to "none" you must always provide vectors yourself. Could be any other "text2vec-*" also.
ModuleConfig: map[string]interface{}{
"text2vec-openai": map[string]interface{}{},
"generative-openai": map[string]interface{}{},
},
}
// add the schema
err = client.Schema().ClassCreator().WithClass(classObj).Do(context.Background())
if err != nil {
panic(err)
}
}
echo '{
"class": "Question",
"vectorizer": "text2vec-openai",
"moduleConfig": {
"text2vec-openai": {},
"generative-openai": {}
}
}' | curl \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $WEAVIATE_API_KEY" \
-d @- \
https://WEAVIATE_INSTANCE_URL/v1/schema # Replace WEAVIATE_INSTANCE_URL with your instance URL
The collection has these properties:
- Collection name:
Question
- Vectorizer module:
text2vec-openai
- Generative module:
generative-openai
Load data
This example code downloads a small data set and uploads it to your WCS instance. The example assumes your collection has a schema already defined.
To upload the data, follow these steps in your client code:
- Create a client connection.
- Add the batch import code after the client creation code.
- Run the code.
- Python (v4)
- Python (v3)
- JS/TS (Beta)
- JS/TS
- Go
- Curl
resp = requests.get('https://raw.githubusercontent.com/weaviate-tutorials/quickstart/main/data/jeopardy_tiny.json')
data = json.loads(resp.text) # Load data
question_objs = list()
for i, d in enumerate(data):
question_objs.append({
"answer": d["Answer"],
"question": d["Question"],
"category": d["Category"],
})
questions = client.collections.get("Question")
questions.data.insert_many(question_objs)
import requests
import json
resp = requests.get('https://raw.githubusercontent.com/weaviate-tutorials/quickstart/main/data/jeopardy_tiny.json')
data = json.loads(resp.text) # Load data
client.batch.configure(batch_size=100) # Configure batch
with client.batch as batch: # Initialize a batch process
for i, d in enumerate(data): # Batch import data
print(f"importing question: {i+1}")
properties = {
"answer": d["Answer"],
"question": d["Question"],
"category": d["Category"],
}
batch.add_data_object(
data_object=properties,
class_name="Question"
)
async function getJsonData() {
const file = await fetch('https://raw.githubusercontent.com/weaviate-tutorials/quickstart/main/data/jeopardy_tiny.json');
return file.json();
}
async function importQuestions() {
// Get the questions directly from the URL
const myCollection = client.collections.get('Question');
const data = await getJsonData();
const result = await myCollection.data.insertMany(data)
console.log('We just bulk inserted',result);
}
await importQuestions();
async function getJsonData() {
const file = await fetch('https://raw.githubusercontent.com/weaviate-tutorials/quickstart/main/data/jeopardy_tiny.json');
return file.json();
}
async function importQuestions() {
// Get the questions directly from the URL
const data = await getJsonData();
// Prepare a batcher
let batcher: ObjectsBatcher = client.batch.objectsBatcher();
let counter = 0;
const batchSize = 100;
for (const question of data) {
// Construct an object with a class and properties 'answer' and 'question'
const obj = {
class: 'Question',
properties: {
answer: question.Answer,
question: question.Question,
category: question.Category,
},
};
// add the object to the batch queue
batcher = batcher.withObject(obj);
// When the batch counter reaches batchSize, push the objects to Weaviate
if (counter++ == batchSize) {
// flush the batch queue
const res = await batcher.do();
console.log(res);
// restart the batch queue
counter = 0;
batcher = client.batch.objectsBatcher();
}
}
// Flush the remaining objects
const res = await batcher.do();
console.log(res);
}
await importQuestions();
package main
import (
"context"
"encoding/json"
"net/http"
"github.com/weaviate/weaviate-go-client/v4/weaviate"
"github.com/weaviate/weaviate-go-client/v4/weaviate/auth"
"github.com/weaviate/weaviate/entities/models"
)
func main() {
cfg := weaviate.Config{
Host: "WEAVIATE_INSTANCE_URL/", // Replace with your Weaviate endpoint
Scheme: "https",
AuthConfig: auth.ApiKey{Value: "YOUR-WEAVIATE-API-KEY"}, // Replace with your Weaviate instance API key
Headers: map[string]string{
"X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY", // Replace with your inference API key
},
}
client, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}
// Retrieve the data
data, err := http.DefaultClient.Get("https://raw.githubusercontent.com/weaviate-tutorials/quickstart/main/data/jeopardy_tiny.json")
if err != nil {
panic(err)
}
defer data.Body.Close()
// Decode the data
var items []map[string]string
if err := json.NewDecoder(data.Body).Decode(&items); err != nil {
panic(err)
}
// convert items into a slice of models.Object
objects := make([]*models.Object, len(items))
for i := range items {
objects[i] = &models.Object{
Class: "Question",
Properties: map[string]any{
"category": items[i]["Category"],
"question": items[i]["Question"],
"answer": items[i]["Answer"],
},
}
}
// batch write items
batchRes, err := client.Batch().ObjectsBatcher().WithObjects(objects...).Do(context.Background())
if err != nil {
panic(err)
}
for _, res := range batchRes {
if res.Result.Errors != nil {
panic(res.Result.Errors.Error)
}
}
}
# Replace with your Weaviate endpoint
API_URL="http://WEAVIATE_INSTANCE_URL/v1/batch/objects"
# Replace with your Inference API token
OPENAI_API_TOKEN="<OpenAI-API-Token>"
# Set batch size
BATCH_SIZE=100
# Read the JSON file and loop through its entries
lines_processed=0
batch_data="{\"objects\": ["
cat jeopardy_tiny.json | jq -c '.[]' | while read line; do
# Concatenate lines
line=$(echo "$line" | jq "{class: \"Question\", properties: {answer: .Answer, question: .Question, category: .Category}}")
if [ $lines_processed -eq 0 ]; then
batch_data+=$line
else
batch_data+=",$line"
fi
lines_processed=$((lines_processed + 1))
# If the batch is full, send it to the API using curl
if [ $lines_processed -eq $BATCH_SIZE ]; then
batch_data+="]}"
curl -X POST "$API_URL" \
-H "Content-Type: application/json" \
-H "X-OpenAI-Api-Key: $OPENAI_API_TOKEN" \
-d "$batch_data"
echo "" # Print a newline for better output formatting
# Reset the batch data and counter
lines_processed=0
batch_data="{\"objects\": ["
fi
done
# Send the remaining data (if any) to the API using curl
if [ $lines_processed -ne 0 ]; then
batch_data+="]}"
curl -X POST "$API_URL" \
-H "Content-Type: application/json" \
-H "X-OpenAI-Api-Key: $OPENAI_API_TOKEN" \
-d "$batch_data"
echo "" # Print a newline for better output formatting
fi
Query your data
Weaviate supports a variety of search methods. A near_text
search vectorizes the search string and returns objects that have vectors that are most similar to it. This example performs a nearText
search on the Question
data collection.
To search for objects in the Question
collection that have vectors that are similar to the vector for biology
, run this example code:
- Python (v4)
- Python (v3)
- JS/TS (Beta)
- JS/TS
- Go
- Curl
import weaviate
import weaviate.classes as wvc
import os
client = weaviate.connect_to_wcs(
cluster_url=os.getenv("WCS_URL"),
auth_credentials=weaviate.auth.AuthApiKey(os.getenv("WCS_API_KEY")),
headers={
"X-OpenAI-Api-Key": os.environ["OPENAI_APIKEY"] # Replace with your inference API key
}
)
try:
pass # Replace with your code. Close client gracefully in the finally block.
questions = client.collections.get("Question")
response = questions.query.near_text(
query="biology",
limit=2
)
print(response.objects[0].properties) # Inspect the first object
finally:
client.close() # Close client gracefully
import weaviate
import json
client = weaviate.Client(
url = "https://WEAVIATE_INSTANCE_URL", # Replace with your Weaviate endpoint
auth_client_secret=weaviate.auth.AuthApiKey(api_key="YOUR-WEAVIATE-API-KEY"), # Replace with your Weaviate instance API key
additional_headers = {
"X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY" # Replace with your inference API key
}
)
response = (
client.query
.get("Question", ["question", "answer", "category"])
.with_near_text({"concepts": ["biology"]})
.with_limit(2)
.do()
)
print(json.dumps(response, indent=4))
import weaviate, { WeaviateClient } from 'weaviate-client';
const client: WeaviateClient = await weaviate.connectToWCS(
'YOUR-WCS-CLUSTER-URL',
{
authCredentials: new weaviate.ApiKey('YOUR-WEAVIATE-API-KEY'),
headers: {
'X-OpenAI-Api-Key': 'YOUR-OPENAI-API-KEY', // Replace with your inference API key
}
}
)
async function nearTextQuery() {
const myCollection = client.collections.get('Question');
const result = await myCollection.query.nearText(['biology'],{
returnProperties: ['question', 'answer', 'category'],
limit:2
});
console.log(JSON.stringify(result.objects, null, 2));
return result;
}
await nearTextQuery();
import weaviate, { WeaviateClient, ObjectsBatcher, ApiKey } from 'weaviate-ts-client';
import fetch from 'node-fetch';
const client: WeaviateClient = weaviate.client({
scheme: 'https',
host: 'WEAVIATE_INSTANCE_URL', // Replace with your Weaviate endpoint
apiKey: new ApiKey('YOUR-WEAVIATE-API-KEY'), // Replace with your Weaviate instance API key
headers: { 'X-OpenAI-Api-Key': 'YOUR-OPENAI-API-KEY' }, // Replace with your inference API key
});
async function nearTextQuery() {
const res = await client.graphql
.get()
.withClassName('Question')
.withFields('question answer category')
.withNearText({concepts: ['biology']})
.withLimit(2)
.do();
console.log(JSON.stringify(res, null, 2));
return res;
}
await nearTextQuery();
await nearTextWhereQuery();
package main
import (
"context"
"fmt"
"github.com/weaviate/weaviate-go-client/v4/weaviate"
"github.com/weaviate/weaviate-go-client/v4/weaviate/auth"
"github.com/weaviate/weaviate-go-client/v4/weaviate/graphql"
)
func main() {
cfg := weaviate.Config{
Host: "WEAVIATE_INSTANCE_URL/", // Replace with your Weaviate endpoint
Scheme: "https",
AuthConfig: auth.ApiKey{Value: "YOUR-WEAVIATE-API-KEY"}, // Replace with your Weaviate instance API key
Headers: map[string]string{"X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY"}, // Replace with your inference API key
}
client, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}
fields := []graphql.Field{
{Name: "question"},
{Name: "answer"},
{Name: "category"},
}
nearText := client.GraphQL().
NearTextArgBuilder().
WithConcepts([]string{"biology"})
result, err := client.GraphQL().Get().
WithClassName("Question").
WithFields(fields...).
WithNearText(nearText).
WithLimit(2).
Do(context.Background())
if err != nil {
panic(err)
}
fmt.Printf("%v", result)
}
echo '{
"query": "{
Get {
Question (
limit: 2
nearText: {
concepts: [\"biology\"],
}
) {
question
answer
category
}
}
}"
}' | tr -d "\n" | curl \
-X POST \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $WEAVIATE_API_KEY" \
-H "X-OpenAI-Api-Key: $OPENAI_API_KEY" \
-d @- \
https://WEAVIATE_INSTANCE_URL/v1/graphql # Replace WEAVIATE_INSTANCE_URL with your instance URL # Replace this with your endpoint
The results are similar to this:
{
"data": {
"Get": {
"Question": [
{
"answer": "DNA",
"category": "SCIENCE",
"question": "In 1953 Watson & Crick built a model of the molecular structure of this, the gene-carrying substance"
},
{
"answer": "Liver",
"category": "SCIENCE",
"question": "This organ removes excess glucose from the blood & stores it as glycogen"
}
]
}
}
}
Next steps
- If you want to try out Weaviate and don't need to save your work, continue with a sandbox cluster.
- If you want to build with Weaviate or if you need a persistent cluster, enter your billing details and create a managed cluster.
- To learn how Weaviate can help you build your project, review the Weaviate documentation.
Support
For questions and support, try the following resources:
Weaviate also offers paid support services. If you have a contract with Weaviate, contact your sales representative for details.