Skip to main content

Quickstart: with cloud resources

Expected time: 30 minutes Prerequisites: None

What you will learn

In this quickstart guide, you will:

  1. Set up Weaviate. (10 minutes)
  2. Populate the database. (10 minutes)
  3. Perform a semantic search and retrieval augmented generation (RAG). (10 minutes)
tip

This tutorial uses a Sandbox instance on Weaviate Cloud, and the OpenAI API. If you prefer to use locally hosted resources, see QuickStart: locally hosted.

Prerequisites​

You will need accounts with Weaviate Cloud and OpenAI.

The Weaviate Sandbox is free, but the OpenAI usage may incur a small cost (e.g. < 10c US). If you have another, preferred model provider, you can use that instead.

For Python users

We have (a Jupyter notebook) available, or you can try it on Google Colab.

Try it yourself

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

Step 1: Set up Weaviate​

1.1 Create a Weaviate database​

Go the WCD homepage and create a free Sandbox instance.

  1. Log onto WCD.
  2. Click on Clusters on the sidebar.
  3. In the following pane, click Create cluster.
Create a cluster
Click on this button to start cluster creation

  1. Give your cluster a name.
  2. Set your preferred cloud region.
  3. Click "Create".
Create a Sandbox Cluster
Populate these fields and create a sandbox.

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

1.2 Install a client library​

We recommend using a client library to work with Weaviate. Follow the instructions below to install one of the official client libraries, available in Python, JavaScript/TypeScript, Go, and Java.

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

pip install -U weaviate-client

1.3: Connect to Weaviate​

Now you can connect to your Weaviate instance. Get the instance REST Endpoint URL and the Administrator API Key from the WCD console as shown below.

Get the (REST) endpoint URL
Grab the REST Endpoint URL.
Get the admin API key
Grab the Admin API key.

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.

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

# Best practice: store your credentials in environment variables
wcd_url = os.environ["WCD_URL"]
wcd_api_key = os.environ["WCD_API_KEY"]

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

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

client.close()  # Free up resources

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 the database​

Now, we can populate our database by first defining a collection then adding data.

2.1 Define a collection​

What is a collection?

A collection is a set of objects that share the same data structure, like a table in relational databases or a collection in NoSQL databases. A collection also includes additional configurations that define how the data objects are stored and indexed.

The following example creates a collection called Question with:

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
wcd_url = os.environ["WCD_URL"]
wcd_api_key = os.environ["WCD_API_KEY"]

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

questions = client.collections.create(
    name="Question",
    vectorizer_config=Configure.Vectorizer.text2vec_openai(),   # Configure the OpenAI embedding integration
    generative_config=Configure.Generative.openai()             # Configure the OpenAI generative AI integration
)

client.close()  # Free up resources

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

What models are being used?

You can optionally specify the model in the collection definition. As we did not specify models in the collection definition above, these integrations will use the Weaviate-defined default models.


See the model providers integration section for more information.

Do you prefer a different setup?

Weaviate is very flexible. If you prefer a different model provider integration, or prefer to import your own vectors, see one of the following guides:

Prefer a different model provider?

See this section for information on how to user another provider, such as AWS, Cohere, Google, and many more.

Want to specify object vectors?

If you prefer to add vectors yourself along with the object data, see Starter Guide: Bring Your Own Vectors.

2.2 Add objects​

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.

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

# Best practice: store your credentials in environment variables
wcd_url = os.environ["WCD_URL"]
wcd_api_key = os.environ["WCD_API_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=Auth.api_key(wcd_api_key),             # Replace with your Weaviate Cloud key
    headers={"X-OpenAI-Api-Key": openai_api_key},           # Replace with your OpenAI API key
)

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

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

with questions.batch.dynamic() as batch:
    for d in data:
        batch.add_object({
            "answer": d["Answer"],
            "question": d["Question"],
            "category": d["Category"],
        })

client.close()  # Free up resources

Run this code to add the demo data.

OpenAI API key in the header

Note that this code includes an additional header for the OpenAI API key. Weaviate uses this key to generate vector embeddings for the data objects as they are being added.

Step 3: Queries​

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

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.

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

# Best practice: store your credentials in environment variables
wcd_url = os.environ["WCD_URL"]
wcd_api_key = os.environ["WCD_API_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=Auth.api_key(wcd_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.get("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

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 OpenAI API key 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.

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

# Best practice: store your credentials in environment variables
wcd_url = os.environ["WCD_URL"]
wcd_api_key = os.environ["WCD_API_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=Auth.api_key(wcd_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.get("Question")

response = questions.generate.near_text(
    query="biology",
    limit=2,
    grouped_task="Write a tweet with emojis about these facts."
)

print(response.generated)  # Inspect the generated text

client.close()  # Free up resources

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

Recap​

In this quickstart guide, you:

  • Created a Serverless Weaviate sandbox instance on Weaviate Cloud.
  • Defined a collection and added data.
  • Performed queries, including:
    • Semantic search, and
    • Retrieval augmented generation.

Where to go next is up to you. We include some suggested steps and resources below.

Next​

Try these additional resources to learn more about Weaviate:

More on search

See how to perform searches, such as keyword, similarity, hybrid, image, filtered and reranked searches.

Manage data

See how to manage data, such as manage collections, create objects, batch import data and use multi-tenancy.

RAG

Check out the Starter guide: retrieval augmented generation, and the Weaviate Academy unit on chunking.

Workshops and office hours

We hold in-person and online workshops, office hours and events for different experience levels. Join us!

FAQs & Troubleshooting​

We provide answers to some common questions, or potential issues below.

Questions​

Can I use different integrations?​

See answer

In this example, we use the OpenAI inference API. But you can use others.

If you do want to change the embeddings, or the generative AI integrations, you can. You will need to:

  • Ensure that the Weaviate module is available in the Weaviate instance you are using,
  • Modify your collection definition to use your preferred integration, and
  • Make sure to use the right API key(s) (if necessary) for your integration.

See the model providers integration section for more information.

Troubleshooting​

If you see Error: Name 'Question' already used as a name for an Object class​

See answer

You may see this error if you try to create a collection that already exists in your instance of Weaviate. In this case, you can follow these instructions to delete the collection.

You can delete any unwanted collection(s), along with the data that they contain.

Deleting a collection also deletes its objects

When you delete a collection, you delete all associated objects!

Be very careful with deletes on a production database and anywhere else that you have important data.

This code deletes a collection and its objects.

# collection_name can be a string ("Article") or a list of strings (["Article", "Category"])
client.collections.delete(collection_name)  # THIS WILL DELETE THE SPECIFIED COLLECTION(S) AND THEIR OBJECTS

# Note: you can also delete all collections in the Weaviate instance with:
# client.collections.delete_all()

How to confirm collection creation​

See answer

If you are not sure whether the collection has been created, check the schema endpoint.

Replace WEAVIATE_INSTANCE_URL with your instance's REST Endpoint URL.:

https://WEAVIATE_INSTANCE_URL/v1/schema

You should see:

{
    "classes": [
        {
            "class": "Question",
            ...  // truncated additional information here
            "vectorizer": "text2vec-openai"
        }
    ]
}

Where the schema should indicate that the Question collection has been added.

REST & GraphQL in Weaviate

Weaviate uses a combination of RESTful and GraphQL APIs. In Weaviate, RESTful API endpoints can be used to add data or obtain information about the Weaviate instance, and the GraphQL interface to retrieve data.

How to confirm data import​

See answer

To confirm successful data import, check the objects endpoint to verify that all objects are imported.

Replace WEAVIATE_INSTANCE_URL with your instance REST Endpoint URL:

https://WEAVIATE_INSTANCE_URL/v1/objects

You should see:

{
    "deprecations": null,
    "objects": [
        ...  // Details of each object
    ],
    "totalResults": 10  // You should see 10 results here
}

Where you should be able to confirm that you have imported all 10 objects.

If the nearText search is not working​

See answer

To perform text-based (nearText) similarity searches, you need to have a vectorizer enabled, and configured in your collection.

Make sure the vectorizer is configured like this.

If the search still doesn't work, contact us!

Questions and feedback​

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