Skip to main content

P3_101A Weaviate Academy Preparation

info

This course was written for the Weaviate Python client API (v3), and is now deprecated.

If you are new to Weaviate, we recommend you start with one of the 100-level courses written with the v4 client API, such as those for working with text data, your own vectors, or multimodal data.

Overview​

Follow this short guide to make sure that you are set up to use Weaviate with the Python client.

Python & Python client​

If you have not yet set up Python and the Weaviate Python client, follow the instructions below.

Install Python​

You can install Python 3 in a variety of ways. One easy way is to use an appropriate installer for your system as per instructions on Python.org.

Install the Weaviate client​

Virtual environments

It is best practice to use virtual environments to isolate projects.

If you're not familiar with virtual environments, we highly recommend reading up on them - this tutorial on FreeCodeCamp is a good resource, as is this article on RealPython, which goes a little more in-depth.

You will also need the following libraries:

weaviate-client

Activate your virtual environment, and install the Weaviate client with:

pip install weaviate-client

Running your Python code​

We recommend running Python code in a Jupyter notebook. You can install the library by running

pip install notebook

Then running the shown code in a Jupyter notebook. Of course, you can also run it in any way that you prefer.

New to Jupyter?

To learn how to use Jupyter notebooks, try this tutorial.

Weaviate​

Instance access​

We will be accessing a pre-built instance of Weaviate throughout the course, located at https://edu-demo.weaviate.network.

You can connect to the pre-built instance with a read-only Weaviate API key.

Confirm that you can run the following code in your Python environment.

import weaviate
import os

client = weaviate.Client(
    url="https://edu-demo.weaviate.network",
    auth_client_secret=weaviate.auth.AuthApiKey(api_key="learn-weaviate"),  # A read-only API Key for the Weaviate instance
)

print(client.is_ready()) # This should return `True`
py docs  API docs

If everything works, the code returns True.

Inference API Key​

We will be using OpenAI's API, so you will need an API key.

If you haven't yet, create an OpenAI account, and create a free API key here.

Then, instantiate the client as shown below, replacing YOUR-OPENAI-API-KEY with your own API key for OpenAI.

import weaviate

client = weaviate.Client(
    url="https://edu-demo.weaviate.network",
    auth_client_secret=weaviate.auth.AuthApiKey(api_key="learn-weaviate"),  # A read-only API Key for the Weaviate instance
    additional_headers={
        "X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY"  # Replace with your OPENAI API key
    }
)
py docs  API docs

Code examples​

Client instantiation​

For brevity, many code examples in the Weaviate Academy will not show the instantiation of the client. So, where you see examples such as:

import json

response = client.query.get(
    "JeopardyQuestion",
    ["question", "answer"]
).with_near_text(
    {"concepts": ["intergalactic travel"]}
).with_limit(2).do()

print(json.dumps(response, indent=2))
py docs  API docs

You will need to instantiate the client as shown in the previous section. So, the above code would become:

import weaviate
import json

client = weaviate.Client(
    url="https://edu-demo.weaviate.network",
    auth_client_secret=weaviate.auth.AuthApiKey(api_key="learn-weaviate"),  # A read-only API Key for the Weaviate instance
    additional_headers={
        "X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY"  # Replace with your OPENAI API key
    }
)

response = client.query.get(
    "JeopardyQuestion",
    ["question", "answer"]
).with_near_text(
    {"concepts": ["intergalactic travel"]}
).with_limit(2).do()

print(json.dumps(response, indent=2))
py docs  API docs

GraphQL​

Weaviate Academy units are written to be used with a client library such as Python. So, you will not need to run GraphQL or REST queries directly.

But note that we also show raw GraphQL/REST queries as well as the Python code where relevant to help you learn the underlying query structures.

So please be aware that when we show a query such as this:

import json

response = client.query.get(
    "JeopardyQuestion",
    ["question", "answer"]
).with_near_text(
    {"concepts": ["intergalactic travel"]}
).with_limit(2).do()

print(json.dumps(response, indent=2))
py docs  API docs

This is what happens under the hood:

{
  Get {
    JeopardyQuestion (
      nearText: {
        concepts: ["intergalactic travel"]
        }
      limit: 2
    ) {
      question
      answer
    }
  }
}

We will show them in separate tabs going forward where applicable, like so:

This tab will show Python code.

Raw GraphQL queries​

The Weaviate Python client can run raw GraphQL queries. You can also use the Weaviate Query app.

In Python, you can run a GraphQL query directly with:

gql_query = """
# ===== Equivalent GraphQL example =====
{
  Get {
    JeopardyQuestion (
      nearText: {
        concepts: ["intergalactic travel"]
        }
      limit: 2
    ) {
      question
      answer
    }
  }
}
# ===== END Equivalent GraphQL example =====
"""

gql_response = client.query.raw(gql_query)
print(json.dumps(gql_response, indent=2))
py docs  API docs

Key takeaways​

  • You have installed the Weaviate client library in your preferred environment.
  • You have an OpenAI inference key.
  • You have some way of running Python code.
  • You know how to instantiate the Weaviate Python client, and run the shown example code.
  • The Academy units will show Python code, but also raw GraphQL or REST snippets where applicable.

Questions and feedback​

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