Weaviate Cloud Quickstart

Expected time: 30 minutes

What you will learn

This quickstart shows you how to combine Weaviate Cloud and Weaviate Embeddings to:

1. Set up a Weaviate instance. (10 minutes)
2. Add and vectorize your data. (10 minutes)
3. Perform a semantic search and retrieval augmented generation (RAG). (10 minutes)

Notes:

• The code examples here are self-contained. You can copy and paste them into your own environment to try them out.

Requirements

• A Weaviate Cloud account.
• In order to perform Retrieval Augmented Generation (RAG) in the last step, you will need a Cohere account. You can use a free Cohere trial API key. If you have another preferred model provider, you can use that instead of Cohere.

---

Step 1: Set up Weaviate Cloud

1.1 Create a cluster

Weaviate offers the following cluster options:

• Sandbox clusters: free short-term cluster for development purposes.
• Serverless clusters: permanent production-ready environment.

Go to the Weaviate Cloud console and create a free Sandbox instance.

note

• Cluster provisioning typically takes 1-3 minutes.
• When the cluster is ready, Weaviate Cloud displays a checkmark (✔️) next to the cluster name.
• Note that Weaviate Cloud adds a random suffix to sandbox cluster names to ensure uniqueness.

TIP: Use the latest Weaviate version!

When possible, try to use the latest Weaviate version. New releases include cutting-edge features, performance enhancements, and critical security updates to keep your application safe and up-to-date.

1.2 Install a client library

The Weaviate Cloud console includes a query interface, but most interactions rely on a Weaviate client. Clients are available in several programming languages. Choose one that makes sense for your project.

To install a client, follow these steps for your language:

PythonJavaScript/TypeScriptGoJava

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

pip install -U weaviate-client

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

npm install weaviate-client

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

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

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>

1.3 Connect to your Weaviate Cloud instance

Now you can connect to your Weaviate instance. You will need the:

• REST Endpoint URL and the
• Administrator API Key.

You can retrieve them both from the WCD console as shown in the interactive example below.

note

New clusters with Weaviate version v1.30 (or later) have RBAC (Role-Based Access Control) enabled by default. These clusters don't come with API keys, you will need to create an API key yourself and assign it a role (admin, viewer or a custom role).

REST vs gRPC endpoints

Weaviate supports both REST and gRPC protocols. For Weaviate Cloud deployments, you only need to provide the REST endpoint URL - the client will automatically configure gRPC.

Once you have the REST Endpoint URL and the Admin API key, you can connect to the Sandbox instance and work with Weaviate.

The example below shows how to connect to Weaviate and perform a basic operation, like checking the cluster status.

PythonJavaScript/TypeScriptGoJavaCurl

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

quickstart_check_readiness.py

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

# Best practice: store your credentials in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,
    auth_credentials=Auth.api_key(weaviate_api_key),
)

print(client.is_ready())  # Should print: `True`

client.close()  # Free up resources

quickstart_check_readiness.ts

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

// Best practice: store your credentials in environment variables
const weaviateUrl = process.env.WEAVIATE_URL as string;
const weaviateApiKey = process.env.WEAVIATE_API_KEY as string;

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  weaviateUrl, // Replace with your Weaviate Cloud URL
  {
    authCredentials: new weaviate.ApiKey(weaviateApiKey), // Replace with your Weaviate Cloud API key
  }
);

var clientReadiness = await client.isReady();
console.log(clientReadiness); // Should return `true`

client.close(); // Close the client connection

quickstart/1_check_readiness/main.go

// Set these environment variables
// WEAVIATE_HOSTNAME            your Weaviate instance hostname
// WEAVIATE_API_KEY          your Weaviate instance API key

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/weaviate/weaviate-go-client/v5/weaviate"
    "github.com/weaviate/weaviate-go-client/v5/weaviate/auth"
)

func main() {
    cfg := weaviate.Config{
        Host:       os.Getenv("WEAVIATE_HOSTNAME"),
        Scheme:     "https",
        AuthConfig: auth.ApiKey{Value: os.Getenv("WEAVIATE_API_KEY")},
    }

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

    // Check the connection
    ready, err := client.Misc().ReadyChecker().Do(context.Background())
    if err != nil {
        panic(err)
    }
    fmt.Printf("%v", ready)
}

caution

This client uses the hostname parameter (without the https scheme) instead of a complete URL.

quickstart/IsReady.java

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.WeaviateAuthClient;
import io.weaviate.client.base.Result;

// Set these environment variables
// WEAVIATE_HOSTNAME     Your Weaviate instance hostname
// WEAVIATE_API_KEY      Your Weaviate instance API key

public class IsReady {
  public static void main(String[] args) throws Exception {
    String host = System.getenv("WEAVIATE_HOSTNAME");
    String apiKey = System.getenv("WEAVIATE_API_KEY");

    Config config = new Config("https", host);
    WeaviateClient client = WeaviateAuthClient.apiKey(config, apiKey);

    // check the result
    Result<Boolean> result = client.misc().readyChecker().run();
    System.out.println(result.getResult());

  }
}

caution

This client uses the hostname parameter (without the https scheme) instead of a complete URL.

# Best practice: store your credentials in environment variables
# export WEAVIATE_URL="YOUR_INSTANCE_URL"  # Your Weaviate instance URL
# export WEAVIATE_API_KEY="YOUR_API_KEY"   # Your Weaviate instance API key

curl -w "\nResponse code: %{http_code}\n" \
  -H "Authorization: Bearer $WEAVIATE_API_KEY" \
  $WEAVIATE_URL/v1/.well-known/ready

# You should see "Response code: 200" if the instance is ready

If you did not see any errors, you are ready to proceed. We will replace the simple cluster status check with more meaningful operations in the next steps.

---

Step 2: Populate your database

2.1 Define a collection

The following example creates a collection called Question with:

• The Weaviate Embeddings model integration to create vectors during ingestion & queries.

PythonJavaScript/TypeScriptGoJavaCurl

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

.Vectors.text2vec_xxx with AutoSchema

Defining a collection with Configure.Vectors.text2vec_xxx() with Python client library 4.16.0-4.16.3 will throw an error if no properties are defined and vectorize_collection_name is not set to True.

This is addressed in 4.16.4 of the Weaviate Python client. See this FAQ entry for more details: Invalid properties error in Python client versions 4.16.0 to 4.16.3.

Python and JS/TS client - Vectorizer Configuration API Changes

Starting with Weaviate Python client v4.16.0, the vectorizer configuration API has been updated.
Starting with Weaviate JS/TS client v3.8.0, the vectorizer configuration API has been updated.

Action required: Update to the latest client version and migrate your code to use the new vectorizer configuration API.

quickstart_create_collection.py

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

# Best practice: store your credentials in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,  # Replace with your Weaviate Cloud URL
    auth_credentials=Auth.api_key(weaviate_api_key),  # Replace with your Weaviate Cloud key
)

questions = client.collections.create(
    name="Question",
    vector_config=Configure.Vectors.text2vec_weaviate(),  # Configure the Weaviate Embeddings integration
)

client.close()  # Free up resources

quickstart_create_collection.ts

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

// Best practice: store your credentials in environment variables
const weaviateUrl = process.env.WEAVIATE_URL as string;
const weaviateApiKey = process.env.WEAVIATE_API_KEY as string;

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  weaviateUrl, // Replace with your Weaviate Cloud URL
  {
    authCredentials: new weaviate.ApiKey(weaviateApiKey), // Replace with your Weaviate Cloud API key
  }
);

await client.collections.create({
  name: 'Question',
  vectorizers: vectors.text2VecWeaviate(),
});

client.close(); // Close the client connection

The collection also contains a configuration for the generative (RAG) integration:

• OpenAI generative AI integrations for retrieval augmented generation (RAG).

quickstart/2_1_create_collection/main.go

// Set these environment variables
// WEAVIATE_HOSTNAME            your Weaviate instance hostname
// WEAVIATE_API_KEY          your Weaviate instance API key

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/weaviate/weaviate-go-client/v5/weaviate"
    "github.com/weaviate/weaviate-go-client/v5/weaviate/auth"
    "github.com/weaviate/weaviate/entities/models"
)

func main() {
    cfg := weaviate.Config{
        Host:       os.Getenv("WEAVIATE_HOSTNAME"),
        Scheme:     "https",
        AuthConfig: auth.ApiKey{Value: os.Getenv("WEAVIATE_API_KEY")},
    }

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

    // Define the collection
    classObj := &models.Class{
        Class:      "Question",
        Vectorizer: "text2vec-weaviate",
        ModuleConfig: map[string]interface{}{
            "text2vec-weaviate": map[string]interface{}{},
            "generative-openai": map[string]interface{}{},
        },
    }

    // add the collection
    err = client.Schema().ClassCreator().WithClass(classObj).Do(context.Background())
    if err != nil {
        panic(err)
    }
}

The collection also contains a configuration for the generative (RAG) integration:

• OpenAI generative AI integrations for retrieval augmented generation (RAG).

quickstart/CreateCollection.java

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.schema.model.WeaviateClass;

import java.util.HashMap;
import java.util.Map;

// Set these environment variables
// WEAVIATE_HOSTNAME     Your Weaviate instance hostname
// WEAVIATE_API_KEY      Your Weaviate instance API key

public class CreateCollection {
  public static void main(String[] args) throws Exception {

    String host = System.getenv("WEAVIATE_HOSTNAME");
    String apiKey = System.getenv("WEAVIATE_API_KEY");

    Config config = new Config("https", host);
    WeaviateClient client = WeaviateAuthClient.apiKey(config, apiKey);

    Map<String, Object> text2vecWeaviateSettings = new HashMap<>();
    Map<String, Object> generativeOpenAISettings = new HashMap<>();

    Map<String, Object> moduleConfig = new HashMap<>();
    moduleConfig.put("text2vec-weaviate", text2vecWeaviateSettings);
    moduleConfig.put("generative-openai", generativeOpenAISettings);

    // Create the collection "Question"
    WeaviateClass clazz = WeaviateClass.builder()
      .className("Question")
      .vectorizer("text2vec-weaviate")
      .moduleConfig(moduleConfig)
      .build();

    // Review the response
    Result<Boolean> result = client.schema().classCreator().withClass(clazz).run();
    System.out.println(result);
    Result<WeaviateClass> collectionDefinition = client.schema().classGetter().withClassName("Question").run();
    System.out.println(collectionDefinition.getResult());
  }
}

The collection also contains a configuration for the generative (RAG) integration:

• OpenAI generative AI integrations for retrieval augmented generation (RAG).

# Best practice: store your credentials in environment variables
# export WEAVIATE_URL="YOUR_INSTANCE_URL"  # Your Weaviate instance URL
# export WEAVIATE_API_KEY="YOUR_API_KEY"   # Your Weaviate instance API key

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $WEAVIATE_API_KEY" \
-d '{
  "class": "Question",
  "vectorizer": "text2vec-weaviate",
  "moduleConfig": {
    "text2vec-weaviate": {},
    "generative-cohere": {}
  }
}' \
"$WEAVIATE_URL/v1/schema"

Run this code to create the collection to which you can add data.

2.2 Load the data

We can now add data to our collection.

The following example:

• Loads objects, and
• Adds objects to the target collection (Question) using a batch process.

Batch imports

(Batch imports) are the most efficient way to add large amounts of data, as it sends multiple objects in a single request. See the How-to: Batch import guide for more information.

PythonJavaScript/TypeScriptGoJavaCurl

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

quickstart_import.py

import weaviate
from weaviate.classes.init import Auth
import requests, json, os

# Best practice: store your credentials in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,                                    # Replace with your Weaviate Cloud URL
    auth_credentials=Auth.api_key(weaviate_api_key),             # Replace with your Weaviate Cloud key
)

resp = requests.get(
    "https://raw.githubusercontent.com/weaviate-tutorials/quickstart/main/data/jeopardy_tiny.json"
)
data = json.loads(resp.text)

questions = client.collections.use("Question")

with questions.batch.fixed_size(batch_size=200) as batch:
    for d in data:
        batch.add_object(
            {
                "answer": d["Answer"],
                "question": d["Question"],
                "category": d["Category"],
            }
        )
        if batch.number_errors > 10:
            print("Batch import stopped due to excessive errors.")
            break

failed_objects = questions.batch.failed_objects
if failed_objects:
    print(f"Number of failed imports: {len(failed_objects)}")
    print(f"First failed object: {failed_objects[0]}")

client.close()  # Free up resources

During a batch import, any failed objects can be obtained through batch.failed_objects. Additionally, a running count of failed objects is maintained and can be accessed through batch.number_errors within the context manager. This counter can be used to stop the import process in order to investigate the failed objects or references. Find out more about error handling on the Python client reference page.

quickstart_import.ts

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

// Best practice: store your credentials in environment variables
const weaviateUrl = process.env.WEAVIATE_URL as string;
const weaviateApiKey = process.env.WEAVIATE_API_KEY as string;

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  weaviateUrl, // Replace with your Weaviate Cloud URL
  {
    authCredentials: new weaviate.ApiKey(weaviateApiKey), // Replace with your Weaviate Cloud API key
  }
);

// Load data
async function getJsonData() {
  const file = await fetch(
    'https://raw.githubusercontent.com/weaviate-tutorials/quickstart/main/data/jeopardy_tiny.json'
  );
  return file.json();
}

// Note: The TS client does not have a `batch` method yet
// We use `insertMany` instead, which sends all of the data in one request
async function importQuestions() {
  const questions = client.collections.use('Question');
  const data = await getJsonData();
  const result = await questions.data.insertMany(data);
  console.log('Insertion response: ', result);
}

await importQuestions();

client.close(); // Close the client connection

quickstart/2_2_import/main.go

// Set these environment variables
// WEAVIATE_HOSTNAME            your Weaviate instance hostname
// WEAVIATE_API_KEY          your Weaviate instance API key

package main

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

    "github.com/weaviate/weaviate-go-client/v5/weaviate"
    "github.com/weaviate/weaviate-go-client/v5/weaviate/auth"
    "github.com/weaviate/weaviate/entities/models"
)

func main() {
    cfg := weaviate.Config{
        Host:       os.Getenv("WEAVIATE_HOSTNAME"),
        Scheme:     "https",
        AuthConfig: auth.ApiKey{Value: os.Getenv("WEAVIATE_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)
        }
    }
}

quickstart/Import.java

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.v1.batch.api.ObjectsBatcher;
import io.weaviate.client.v1.data.model.WeaviateObject;
import org.json.JSONArray;
import org.json.JSONObject;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.HashMap;
import java.util.Map;

// Set these environment variables
// WEAVIATE_HOSTNAME     Your Weaviate instance hostname
// WEAVIATE_API_KEY      Your Weaviate instance API key

public class Import {
  public static void main(String[] args) throws Exception {

    String host = System.getenv("WEAVIATE_HOSTNAME");
    String apiKey = System.getenv("WEAVIATE_API_KEY");

    Config config = new Config("https", host);
    WeaviateClient client = WeaviateAuthClient.apiKey(config, apiKey);

    // Get JSON data
    URL url = new URL("https://raw.githubusercontent.com/weaviate-tutorials/quickstart/main/data/jeopardy_tiny.json");
    String jsonData = new BufferedReader(new InputStreamReader(((HttpURLConnection) url.openConnection()).getInputStream()))
      .lines().reduce("", String::concat);

    // Create and execute batch
    ObjectsBatcher batcher = client.batch().objectsBatcher();

    new JSONArray(jsonData).forEach(item -> {
      JSONObject json = (JSONObject) item;
      HashMap<String, Object> properties = new HashMap<>();
      properties.put("category", json.getString("Category"));
      properties.put("question", json.getString("Question"));
      properties.put("answer", json.getString("Answer"));

      batcher.withObject(WeaviateObject.builder()
        .className("Question")
        .properties(properties)
        .build());
    });

    // Flush
    batcher.run();
  }
}

note

• Download the jeopardy_tiny.json file from here before running the following script.
• This assumes you have jq installed.

# Best practice: store your credentials in environment variables
# export WEAVIATE_URL="YOUR_INSTANCE_URL"  # Your Weaviate instance URL
# export WEAVIATE_API_KEY="YOUR_API_KEY"   # Your Weaviate instance API key

# Set batch size
BATCH_ENDPOINT="$WEAVIATE_URL/v1/batch/objects"
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 "$BATCH_ENDPOINT" \
         -H "Content-Type: application/json" \
         -H "Authorization: Bearer $WEAVIATE_API_KEY" \
         -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 "$BATCH_ENDPOINT" \
       -H "Content-Type: application/json" \
       -H "Authorization: Bearer $WEAVIATE_API_KEY" \
       -d "$batch_data"
  echo "" # Print a newline for better output formatting
fi

Run this code to add the demo data.

---

Step 3: Query your data

Weaviate provides a wide range of query tools to help you find the right data. We will try a few searches here.

3.1 Semantic search

Semantic search finds results based on meaning. This is called nearText in Weaviate.

The following example searches for 2 objects whose meaning is most similar to that of biology.

PythonJavaScript/TypeScriptGoJavaCurl

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

quickstart_neartext_query.py

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

# Best practice: store your credentials in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,                                    # Replace with your Weaviate Cloud URL
    auth_credentials=Auth.api_key(weaviate_api_key),             # Replace with your Weaviate Cloud key
)

questions = client.collections.use("Question")

response = questions.query.near_text(
    query="biology",
    limit=2
)

for obj in response.objects:
    print(json.dumps(obj.properties, indent=2))

client.close()  # Free up resources

quickstart_neartext_query.ts

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

// Best practice: store your credentials in environment variables
const weaviateUrl = process.env.WEAVIATE_URL as string;
const weaviateApiKey = process.env.WEAVIATE_API_KEY as string;

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  weaviateUrl, // Replace with your Weaviate Cloud URL
  {
    authCredentials: new weaviate.ApiKey(weaviateApiKey), // Replace with your Weaviate Cloud API key
  }
);

const questions = client.collections.use('Question');

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

result.objects.forEach((item) => {
  console.log(JSON.stringify(item.properties, null, 2));
});

client.close(); // Close the client connection

quickstart/3_1_neartext/main.go

// Set these environment variables
// WEAVIATE_HOSTNAME            your Weaviate instance hostname
// WEAVIATE_API_KEY          your Weaviate instance API key

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/weaviate/weaviate-go-client/v5/weaviate"
    "github.com/weaviate/weaviate-go-client/v5/weaviate/auth"
    "github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
    cfg := weaviate.Config{
        Host:       os.Getenv("WEAVIATE_HOSTNAME"),
        Scheme:     "https",
        AuthConfig: auth.ApiKey{Value: os.Getenv("WEAVIATE_API_KEY")},
    }

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

    ctx := context.Background()

    response, err := client.GraphQL().Get().
        WithClassName("Question").
        WithFields(
            graphql.Field{Name: "question"},
            graphql.Field{Name: "answer"},
            graphql.Field{Name: "category"},
        ).
        WithNearText(client.GraphQL().NearTextArgBuilder().
            WithConcepts([]string{"biology"})).
        WithLimit(2).
        Do(ctx)

    if err != nil {
        panic(err)
    }
    fmt.Printf("%v", response)
}

quickstart/NearText.java

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.graphql.model.GraphQLResponse;
import io.weaviate.client.v1.graphql.query.argument.NearTextArgument;
import io.weaviate.client.v1.graphql.query.builder.GetBuilder;
import io.weaviate.client.v1.graphql.query.fields.Field;
import io.weaviate.client.v1.graphql.query.fields.Fields;

import java.util.HashMap;
import java.util.Map;

// Set these environment variables
// WEAVIATE_HOSTNAME     Your Weaviate instance hostname
// WEAVIATE_API_KEY      Your Weaviate instance API key

public class NearText {
  public static void main(String[] args) throws Exception {

    String host = System.getenv("WEAVIATE_HOSTNAME");
    String apiKey = System.getenv("WEAVIATE_API_KEY");

    Config config = new Config("https", host);
    WeaviateClient client = WeaviateAuthClient.apiKey(config, apiKey);

    NearTextArgument nearText = NearTextArgument.builder()
      .concepts(new String[]{"biology"})
      .build();

    Fields fields = Fields.builder()
      .fields(new Field[]{
        Field.builder().name("question").build(),
        Field.builder().name("answer").build(),
      })
      .build();

    String query = GetBuilder.builder()
      .className("Question")
      .fields(fields)
      .withNearTextFilter(nearText)
      .limit(2)
      .build()
      .buildQuery();

    Result<GraphQLResponse> result = client.graphQL().raw().withQuery(query).run();
    System.out.println(result.getResult());
  }
}

# Best practice: store your credentials in environment variables
# export WEAVIATE_URL="YOUR_INSTANCE_URL"    # Your Weaviate instance URL
# export WEAVIATE_API_KEY="YOUR_API_KEY"     # Your Weaviate instance API key

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" \
    -d @- \
    $WEAVIATE_URL/v1/graphql

Run this code to perform the query. Our query found entries for DNA and species.

Example full response in JSON format

{
  {
    "answer": "DNA",
    "question": "In 1953 Watson & Crick built a model of the molecular structure of this, the gene-carrying substance",
    "category": "SCIENCE"
  },
  {
    "answer": "species",
    "question": "2000 news: the Gunnison sage grouse isn't just another northern sage grouse, but a new one of this classification",
    "category": "SCIENCE"
  }
}

If you inspect the full response, you will see that the word biology does not appear anywhere.

Even so, Weaviate was able to return biology-related entries. This is made possible by vector embeddings that capture meaning. Under the hood, semantic search is powered by vectors, or vector embeddings.

Here is a diagram showing the workflow in Weaviate.

Where did the vectors come from?

Weaviate used the Weaviate Embeddings service to generate a vector embedding for each object during import. During the query, Weaviate similarly converted the query (biology) into a vector.

As we mentioned above, this is optional. See Starter Guide: Bring Your Own Vectors if you would prefer to provide your own vectors.

More search types available

Weaviate is capable of many types of searches. See, for example, our how-to guides on similarity searches, keyword searches, hybrid searches, and filtered searches.

3.2 Retrieval augmented generation

Retrieval augmented generation (RAG), also called generative search, combines the power of generative AI models such as large language models (LLMs) with the up-to-date truthfulness of a database.

RAG works by prompting a large language model (LLM) with a combination of a user query and data retrieved from a database.

This diagram shows the RAG workflow in Weaviate.

The following example combines the same search (for biology) with a prompt to generate a tweet.

PythonJavaScript/TypeScriptGoJavaCurl

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

We are using the OpenAI generative AI integrations for retrieval augmented generation (RAG).

quickstart_rag.py

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


# Best practice: store your credentials in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]
openai_api_key = os.environ["OPENAI_APIKEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url,  # Replace with your Weaviate Cloud URL
    auth_credentials=Auth.api_key(
        weaviate_api_key
    ),  # Replace with your Weaviate Cloud key
    headers={"X-OpenAI-Api-Key": openai_api_key},  # Replace with your OpenAI API key
)

questions = client.collections.use("Question")

response = questions.generate.near_text(
    query="biology",
    limit=2,
    grouped_task="Write a tweet with emojis about these facts.",
    generative_provider=GenerativeConfig.openai(),  # Configure the OpenAI generative integration for RAG
)

print(response.generative.text)  # Inspect the generated text

client.close()  # Free up resources

We are using the OpenAI generative AI integrations for retrieval augmented generation (RAG).

quickstart_rag.ts

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

// Best practice: store your credentials in environment variables
const weaviateUrl = process.env.WEAVIATE_URL as string;
const weaviateApiKey = process.env.WEAVIATE_API_KEY as string;
const openAiKey = process.env.OPENAI_API_KEY as string;

const client: WeaviateClient = await weaviate.connectToWeaviateCloud(
  weaviateUrl, // Replace with your Weaviate Cloud URL
  {
    authCredentials: new weaviate.ApiKey(weaviateApiKey), // Replace with your Weaviate Cloud API key
    headers: {
      'X-OpenAI-Api-Key': openAiKey, // Replace with your OpenAI API key
    },
  }
);

const questions = client.collections.use('Question');

const result = await questions.generate.nearText(
  'biology',
  {
    groupedTask: 'Write a tweet with emojis about these facts.',
    config: generativeParameters.openAI(),
  },
  {
    limit: 2,
  }
);

console.log(result.generative);

client.close(); // Close the client connection

quickstart/3_2_rag/main.go

// Set these environment variables
// WEAVIATE_HOSTNAME            your Weaviate instance hostname
// WEAVIATE_API_KEY          your Weaviate instance API key
// OPENAI_APIKEY           your OpenAI API key

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/weaviate/weaviate-go-client/v5/weaviate"
    "github.com/weaviate/weaviate-go-client/v5/weaviate/auth"
    "github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

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

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

    ctx := context.Background()

    generatePrompt := "Write a tweet with emojis about these facts."

    gs := graphql.NewGenerativeSearch().GroupedResult(generatePrompt)

    response, err := client.GraphQL().Get().
        WithClassName("Question").
        WithFields(
            graphql.Field{Name: "question"},
            graphql.Field{Name: "answer"},
            graphql.Field{Name: "category"},
        ).
        WithGenerativeSearch(gs).
        WithNearText(client.GraphQL().NearTextArgBuilder().
            WithConcepts([]string{"biology"})).
        WithLimit(2).
        Do(ctx)

    if err != nil {
        panic(err)
    }
    fmt.Printf("%v", response)
}

quickstart/RAG.java

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.graphql.model.GraphQLResponse;
import io.weaviate.client.v1.graphql.query.argument.NearTextArgument;
import io.weaviate.client.v1.graphql.query.builder.GetBuilder;
import io.weaviate.client.v1.graphql.query.fields.Field;
import io.weaviate.client.v1.graphql.query.fields.Fields;
import io.weaviate.client.v1.graphql.query.fields.GenerativeSearchBuilder;

import java.util.HashMap;
import java.util.Map;

// Set these environment variables
// WEAVIATE_HOSTNAME     Your Weaviate instance hostname
// WEAVIATE_API_KEY      Your Weaviate instance API key
// OPENAI_APIKEY         Your OpenAI API key

public class RAG {
  public static void main(String[] args) throws Exception {

    String host = System.getenv("WEAVIATE_HOSTNAME");
    String apiKey = System.getenv("WEAVIATE_API_KEY");
    String openAiKey = System.getenv("OPENAI_APIKEY");

    Map<String, String> headers = new HashMap<String, String>() { {
      put("X-OpenAI-Api-Key", openAiKey);
    } };

    Config config = new Config("https", host, headers);
    WeaviateClient client = WeaviateAuthClient.apiKey(config, apiKey);

    NearTextArgument nearText = NearTextArgument.builder()
      .concepts(new String[]{"biology"})
      .build();

    GenerativeSearchBuilder ragQuery = GenerativeSearchBuilder.builder()
      .groupedResultTask("Write a tweet with emojis about these facts.")
      .build();

    Fields fields = Fields.builder()
      .fields(new Field[]{
        Field.builder().name("question").build(),
        Field.builder().name("answer").build(),
      })
      .build();

    String query = GetBuilder.builder()
      .className("Question")
      .fields(fields)
      .withNearTextFilter(nearText)
      .withGenerativeSearch(ragQuery)
      .limit(2)
      .build()
      .buildQuery();

    Result<GraphQLResponse> result = client.graphQL().raw().withQuery(query).run();
    System.out.println(result.getResult());
  }
}

# Best practice: store your credentials in environment variables
# export WEAVIATE_URL="YOUR_INSTANCE_URL"    # Your Weaviate instance URL
# export WEAVIATE_API_KEY="YOUR_API_KEY"     # Your Weaviate instance API key
# export COHERE_APIKEY="YOUR_API_KEY"   # Your Cohere API key

echo '{
  "query": "{
    Get {
      Question (
        limit: 2
        nearText: {
          concepts: [\"biology\"],
        }
      ) {
        question
        answer
        category
        _additional {
          generate(
            groupedResult: {
              task: \"\"\"
                Write a tweet with emojis about these facts.
              \"\"\"
            }
          ) {
            groupedResult
            error
          }
        }
      }
    }
  }"
}' | tr -d "\n" | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $WEAVIATE_API_KEY" \
    -H "X-Cohere-Api-Key: $COHERE_APIKEY" \
    -d @- \
    $WEAVIATE_URL/v1/graphql

Cohere API key in the header

Note that this code includes an additional header for the Cohere API key. Weaviate uses this key to access the Cohere generative AI model and perform retrieval augmented generation (RAG).

Run this code to perform the query. Here is one possible response (your response will likely be different).

🧬 In 1953 Watson & Crick built a model of the molecular structure of DNA, the gene-carrying substance! 🧬🔬

🦢 2000 news: the Gunnison sage grouse isn't just another northern sage grouse, but a new species! 🦢🌿 #ScienceFacts #DNA #SpeciesClassification

The response should be new, yet familiar. This is because you have seen the entries above for DNA and species in the semantic search section.

The power of RAG comes from the ability to transform your own data. Weaviate helps you in this journey by making it easy to perform a combined search & generation in just a few lines of code.

---

Next steps

Try these additional resources to learn more about Weaviate:

Serverless Cloud

If you need a production-ready and persistent instance, create a Serverless cluster.

Weaviate Database: Documentation

To learn how Weaviate can help you build your AI project, check out the Weaviate documentation.

Support & feedback

For help with Serverless Cloud, Enterprise Cloud, and Bring Your Own Cloud accounts, contact Weaviate support directly to open a support ticket. To add a support plan, contact Weaviate sales.

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.