Quickstart

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

Create a WCS account

1. Go the WCS 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 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
• Managed clusters.

Sandbox clusters

To create a sandbox cluster, follow these steps:

1. Select the "Free sandbox" tab.
2. Give your cluster a name. WCS 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, WCS 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.

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:

1. Select the "Managed cluster" tab.
2. Give your cluster a name.
3. Select a region.
4. Accept the terms and conditions.
5. 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:

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

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

Python (v3)

Add weaviate-client to your Python environment with pip:

pip install "weaviate-client==3.*"

JS/TS (Beta)

Add weaviate-client to your project with npm:

npm install weaviate-client --tag beta

JS/TS

Add weaviate-ts-client to your project with npm:

npm install weaviate-ts-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.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:

1. Copy the sample client code to a file.
2. Find your WCS cluster URL and API key in the WCS 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 (v4)

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

Python (v3)

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

JS/TS (Beta)

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

JS/TS

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

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

JS/TS (Beta)

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

JS/TS

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

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

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

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

JS/TS (Beta)

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

JS/TS

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

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

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

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

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

JS/TS (Beta)

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

JS/TS

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

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

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

• Community forum
• GitHub
• Slack

Weaviate also offers paid support services. If you have a contract with Weaviate, contact your sales representative for details.