Quickstart

This Quickstart guide shows you how to get started with Weaviate Cloud (WCD).

Create a WCD account

1. Go the WCD homepage.
2. Click, "Register here".

3. Provide an email address and password.
4. After you confirm your email address, return to the login page.
5. Log in to the WCD console.

Create a Weaviate Cluster

When you log into the WCD web console, the Dashboard tab lists your clusters. There are no clusters when you log in to a new account. WCD has short-term, sandbox clusters and permanent, serverless clusters.

To create a cluster, click the 'Create cluster' button on the WCD Dashboard page.

Follow the steps to create a cluster:

• Sandbox clusters
• Serverless clusters.

Sandbox clusters

To create a sandbox cluster, follow these steps:

1. Select the "Free sandbox" tab.
2. Give your cluster a name. WCD adds a random suffix to sandbox cluster names to ensure uniqueness.
3. Verify that "Enable Authentication?" is set to "Yes".
4. Click create.

It takes a minute or two to create the new cluster. When the cluster is ready, WCD displays a check mark (✔️) next to the cluster name.

Sandbox expiration

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.

Serverless clusters

Serverless clusters require billing details. WCD prompts you to add billing details if you have not already added them.

To create a serverless cluster, follow these steps:

1. Select the "Managed cluster" tab.
2. Give your cluster a name.
3. Select a version.
4. Select a region.
5. Accept the terms and conditions.
6. Click create.

It takes a minute or two to create the new cluster. When the cluster is ready, WCD 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:

1. Click the Details button to open the Details panel.

2. To get the API keys, click the API keys button.

3. Copy the API key for the Admin user to a safe place.

4. The cluster URL begins with the cluster name. Copy it to a safe place.

Install a client library

The WCD console includes a query interface, but most most WCD 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

Install the latest, Python client v4, by adding weaviate-client to your Python environment with pip:

pip install -U weaviate-client

JS/TS

Install the latest, JS/TS client v3, by adding weaviate-client to your project with npm:

npm install weaviate-client

Go

Add weaviate-go-client to your project with go get:

go get github.com/weaviate/weaviate-go-client/v4

Java

Add this dependency to your project:

<dependency>
  <groupId>io.weaviate</groupId>
  <artifactId>client</artifactId>
  <version>4.8.3</version>  <!-- Check latest version: https://github.com/weaviate/java-client -->
</dependency>

Connect to your WCD instance

These code samples demonstrate how to connect a Weaviate client to your WCD cluster.

To connect to your cluster, follow these steps for your language:

1. Copy the sample client code to a file.
2. Find your WCD cluster URL and API key in the WCD Console.
3. Create environment variables, or edit the sample code, to pass the URL and API keys to your client.
4. Run the client code.

Python Client v4

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

# Best practice: store your credentials in environment variables
wcd_url = os.environ["WCD_DEMO_URL"]
wcd_api_key = os.environ["WCD_DEMO_RO_KEY"]
openai_api_key = os.environ["OPENAI_APIKEY"]

with 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
    headers={
        'X-OpenAI-Api-key': openai_api_key  # Replace with appropriate header key/value pair for the required API
    }
) as client:  # Use this context manager to ensure the connection is closed
    print(client.is_ready())

  API docs

Python Client v3

import weaviate
import os

client = weaviate.Client(
    url=os.getenv("WEAVIATE_INSTANCE_URL"),  # Replace with your Weaviate endpoint
    auth_client_secret=weaviate.auth.AuthApiKey(api_key=os.getenv("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())

JS/TS Client v3

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

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  '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);

JS/TS Client v2

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);

Go

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)
}

Java

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:

1. Create a client connection.
2. Add the collection definition code after the client creation code.
3. Run the code.

Python Client v4

    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
    )

  API docs

Python Client v3

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)

  API docs

JS/TS Client v3

import { vectorizer, generative } from 'weaviate-client' 

async function createCollection() {
  const questions = await client.collections.create({
    name: 'Question',
    vectorizers: vectorizer.text2VecOpenAI(),
    generative: generative.openAI(),
  })
  console.log(`Collection ${questions.name} created!`);
}
await createCollection();

  API docs

JS/TS Client v2

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();

Go

// Set these environment variables
// WEAVIATE_URL      your Weaviate instance URL, without https prefix
// WEAVIATE_API_KEY  your Weaviate instance API key
// OPENAI_API_KEY    your OpenAI 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"
	"github.com/weaviate/weaviate/entities/models"
)

func main() {
	// Create the client
	cfg := weaviate.Config{
		Host:       os.Getenv("WEAVIATE_URL"),
		Scheme:     "https",
		AuthConfig: auth.ApiKey{Value: os.Getenv("WEAVIATE_API_KEY")},
		Headers: map[string]string{
			"X-OpenAI-Api-Key": os.Getenv("OPENAI_API_KEY"),
		},
	}

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

	classObj := &models.Class{
		Class:      "Question",
		Vectorizer: "text2vec-openai", // If "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)
	}
}

  API docs

Curl

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 WCD instance. The example assumes your collection has a schema already defined.

To upload the data, follow these steps in your client code:

1. Create a client connection.
2. Add the batch import code after the client creation code.
3. Run the code.

Python Client v4

    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)

  API docs

Python Client v3

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"
        )

  API docs

JS/TS Client v3

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 questions = client.collections.get('Question');
  const data = await getJsonData();
  const result = await questions.data.insertMany(data)
  console.log('We just bulk inserted',result);
}
await importQuestions();

  API docs

JS/TS Client v2

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();

Go

// Set these environment variables
// WEAVIATE_URL      your Weaviate instance URL, without https prefix
// WEAVIATE_API_KEY  your Weaviate instance API key
// OPENAI_API_KEY    your OpenAI API key

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"os"

	"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() {
	// Create the client
	cfg := weaviate.Config{
		Host:       os.Getenv("WEAVIATE_URL"),
		Scheme:     "https",
		AuthConfig: auth.ApiKey{Value: os.Getenv("WEAVIATE_API_KEY")},
		Headers: map[string]string{
			"X-OpenAI-Api-Key": os.Getenv("OPENAI_API_KEY"),
		},
	}

	client, err := weaviate.NewClient(cfg)
	if err != nil {
		fmt.Println(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)
		}
	}
}

  API docs

Curl

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

import weaviate
import weaviate.classes as wvc
import os

# Best practice: store your credentials in environment variables
wcd_url = os.environ["WCD_DEMO_URL"]
wcd_api_key = os.environ["WCD_DEMO_RO_KEY"]
openai_api_key = os.environ["OPENAI_APIKEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=wcd_url,                                    # Replace with your Weaviate Cloud URL
    auth_credentials=wvc.init.Auth.api_key(wcd_api_key),    # Replace with your Weaviate Cloud key
    headers={"X-OpenAI-Api-Key": openai_api_key}            # Replace with appropriate header key/value pair for the required API
)

try:
    pass  # Work with the client. 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

  API docs

Python Client v3

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))

  API docs

JS/TS Client v3

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

const weaviateURL = process.env.WEAVIATE_URL as string
const weaviateKey = process.env.WEAVIATE_ADMIN_KEY as string
const openaiKey = process.env.OPENAI_API_KEY as string

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(weaviateURL, {
  authCredentials: new weaviate.ApiKey(weaviateKey),
  headers: {
    'X-OpenAI-Api-Key': openaiKey,  // Replace with your inference API key
  }
})

async function nearTextQuery() {  
  const questions = client.collections.get('Question');

  const result = await questions.query.nearText('biology', {
    limit:2
  });

  for (let object of result.objects) {
    console.log(JSON.stringify(object.properties, null, 2));
  }

  return result;
}
await nearTextQuery();

  API docs

JS/TS Client v2

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();

Go

GoNearText

// Set these environment variables
// WEAVIATE_URL      your Weaviate instance URL, without https prefix
// WEAVIATE_API_KEY  your Weaviate instance API key
// OPENAI_API_KEY    your OpenAI 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"
	"github.com/weaviate/weaviate-go-client/v4/weaviate/graphql"
)

func main() {
	// Create the client
	cfg := weaviate.Config{
		Host:       os.Getenv("WEAVIATE_URL"),
		Scheme:     "https",
		AuthConfig: auth.ApiKey{Value: os.Getenv("WEAVIATE_API_KEY")},
		Headers: map[string]string{
			"X-OpenAI-Api-Key": os.Getenv("OPENAI_API_KEY"),
		},
	}

	client, err := weaviate.NewClient(cfg)
	if err != nil {
		fmt.Println(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)
}

  API docs

Curl

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 serverless cluster.
• To learn how Weaviate can help you build your project, review the Weaviate documentation.

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.