Getting hands-on

Preparation

Obtain a free trial OpenAI API key

This section includes queries using the OpenAI inference endpoint. If you don't already have an OpenAI account, we recommend creating one. At the time of writing, OpenAI provides trial credits which should be sufficient for these exercises.

Overview

Now that you've set up your own Weaviate instance and installed a client, let's get hands-on with Weaviate.

Client instantiation

Create a client object for persistent access to your Weaviate instance. You can set the following parameters:

Host URL (required)
This is the location of your Weaviate instance. The URL resembles
```
https://your-sandbox-uo2vgb1z.weaviate.network
```
Authentication details (optional)
If authentication is enabled, you MUST provide your authentication information here. Otherwise the Weaviate instance will not provide access.
```
AbCdEfGhIjKlMnOpAXB6gbBIaxHDuuwWj5OD
```
Additional headers (optional)
You can provide additional headers. These headers provide API keys for inference services such as Cohere, Hugging Face or OpenAI.

A fully configured client resembles this sample code, edited to match your Weaviate instance.

Python

import weaviate

# Only if authentication enabled; assuming API key authentication
auth_config = weaviate.auth.AuthApiKey(api_key="YOUR-WEAVIATE-API-KEY")  # Replace with your Weaviate instance API key

# Instantiate the client
client = weaviate.Client(
    url="https://example.weaviate.network",
    auth_client_secret=auth_config,  # Only necessary if authentication enabled
    additional_headers={
        "X-Cohere-Api-Key": "YOUR-COHERE-API-KEY",            # Replace with your Cohere key
        "X-HuggingFace-Api-Key": "YOUR-HUGGINGFACE-API-KEY",  # Replace with your Hugging Face key
        "X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY",            # Replace with your OpenAI key
    }
)

Try it out!

Now, connect to your Weaviate instance.

Copy the client code below to a file called connection_example.py.
Edit the file to use your Weaviate URL
Edit the API key to use the key for your sandbox.
You can find the API keys for your sandbox by clicking the "Details" button and looking for "API keys" in the Authentication tab. The key resembles this one.
Run the file.
```
python3 connection_example.py
```

Python

import weaviate
import json

auth_config = weaviate.auth.AuthApiKey(api_key="YOUR-WEAVIATE-API-KEY")  # Replace with your Weaviate API key

# Instantiate the client
client = weaviate.Client(
    url="https://your-endpoint.weaviate.network",  # Replace with your sandbox URL
    auth_client_secret=auth_config,
)

meta_info = client.get_meta()
print(json.dumps(meta_info, indent=2))

Expected output

{
  "hostname": "http://[::]:8080",
  "modules": {
    "generative-openai": {
      "documentationHref": "https://beta.openai.com/docs/api-reference/completions",
      "name": "Generative Search - OpenAI"
    },
    "qna-openai": {
      "documentationHref": "https://beta.openai.com/docs/api-reference/completions",
      "name": "OpenAI Question & Answering Module"
    },
    "ref2vec-centroid": {},
    "text2vec-cohere": {
      "documentationHref": "https://docs.cohere.com/docs/embeddings",
      "name": "Cohere Module"
    },
    "text2vec-huggingface": {
      "documentationHref": "https://huggingface.co/docs/api-inference/detailed_parameters#feature-extraction-task",
      "name": "Hugging Face Module"
    },
    "text2vec-openai": {
      "documentationHref": "https://beta.openai.com/docs/guides/embeddings/what-are-embeddings",
      "name": "OpenAI Module"
    }
  },
  "version": "1.18.2"
}

Congratulations! You've made your first request to a Weaviate API! The meta REST endpoint returns configuration details for your instance.

The Weaviate API allows you to do quite a bit. We will try out some examples in the next sections. For more details, see the API documentation.

Weaviate API and the client

Available APIs

Weaviate uses two API types - REST APIs and GraphQL APIs. They work together to provide a rich set of functionality.

REST APIs vs GraphQL APIs

The REST API provides:

CRUD (Create, Read, Update and Delete) operations
Metadata about the database

The GraphQL API provides:

Data searches
Data object retrieval
Information aggregation
Vector space exploration

You will learn about these capabilities over the course of these units.

What is REST?

REST is an acronym for REpresentational State Transfer.

A REST API provides multiple endpoints, each with its own URL, that can be used to interact with the application.

The endpoints are organized into a hierarchy, with each endpoint representing a resource. The client can then request information about these resources by sending a request to the server.

What is GraphQL?

GraphQL is a query language for APIs.

First released by Facebook in 2015, it is now maintained by the GraphQL Foundation.

GraphQL is a specification for a query language that can be used to request information from a server. GraphQL is a strongly typed language, which means that the client must specify the type of data that it wants to receive.

Access the REST API

You can access the REST API and the GraphQL API with the Weaviate client libraries, or with other tools as long as the tool formats the request properly.

In these examples, the code shown in each set of tabs is functionally the same. Both REST calls request meta information. Both GraphQL calls ask for the same data.

Example 1: REST vs client requests

REST
Python

curl http://localhost:8080/v1/meta

import weaviate

client = weaviate.Client("http://localhost:8080")

print(client.get_meta())

Example 2: GraphQL vs client requests

GraphQL
Python

{
  Get {
    WikiArticle {
      title
      wiki_summary
    }
  }
}

result = client.query.get("WikiArticle", ["title", "wiki_summary"]).do()

Now, let's try out more substantive queries.

Running queries

Connect to our demo instance

Now let's try to connect to a Weaviate demo instance and run some queries on the sample data. The instance has these details:

Demo instance details

url: https://edu-demo.weaviate.network
Weaviate API key: readonly-demo

Use these instance details and see if you can:

Instantiate a Weaviate client
Check that the connection by fetching the metadata as we did above.

Bonus points if you can do it without looking at the snippet below:

Connect to the demo instance

Python

import weaviate
import json

auth_config = weaviate.auth.AuthApiKey(api_key="readonly-demo")

# Instantiate the client
client = weaviate.Client(
    url="https://edu-demo.weaviate.network",
    auth_client_secret=auth_config,
    additional_headers={
        "X-OpenAI-Api-Key": "YOUR-OPENAI-API-KEY",  # Replace with your OpenAI key
    }
)

meta_info = client.get_meta()
print(json.dumps(meta_info, indent=2))

Expected output

{
  "hostname": "http://[::]:8080",
  "modules": {
    "generative-openai": {
      "documentationHref": "https://beta.openai.com/docs/api-reference/completions",
      "name": "Generative Search - OpenAI"
    },
    "qna-openai": {
      "documentationHref": "https://beta.openai.com/docs/api-reference/completions",
      "name": "OpenAI Question & Answering Module"
    },
    "ref2vec-centroid": {},
    "text2vec-cohere": {
      "documentationHref": "https://docs.cohere.com/docs/embeddings",
      "name": "Cohere Module"
    },
    "text2vec-huggingface": {
      "documentationHref": "https://huggingface.co/docs/api-inference/detailed_parameters#feature-extraction-task",
      "name": "Hugging Face Module"
    },
    "text2vec-openai": {
      "documentationHref": "https://beta.openai.com/docs/guides/embeddings/what-are-embeddings",
      "name": "OpenAI Module"
    }
  },
  "version": "1.18.2"
}

Vector searches

The next query searches the WikiCity objects for the cities that are closest to the specified text, which in this case is simply, "Major European city".

To run this query, update the connection file you just created.

Comment out any lines that request meta information
Add the OpenAI authorization key you created earlier
Add the following code snippet

Python

res = client.query.get(
    "WikiCity", ["city_name", "country", "lng", "lat"]
).with_near_text({
    "concepts": ["Major European city"]
}).with_limit(5).do()

print(json.dumps(res, indent=2))

Expected output

{
  "data": {
    "Get": {
      "WikiCity": [
        {
          "city_name": "Paris",
          "country": "France",
          "lat": 48.8566,
          "lng": 2.3522
        },
        {
          "city_name": "London",
          "country": "United Kingdom",
          "lat": 51.5072,
          "lng": -0.1275
        },
        {
          "city_name": "Madrid",
          "country": "Spain",
          "lat": 40.4167,
          "lng": -3.7167
        },
        {
          "city_name": "Berlin",
          "country": "Germany",
          "lat": 52.5167,
          "lng": 13.3833
        },
        {
          "city_name": "Budapest",
          "country": "Hungary",
          "lat": 47.4983,
          "lng": 19.0408
        }
      ]
    }
  }
}

Exercise

Try varying the query concept from "Major European city" to another - what do you see? Is it in line with what you expected?

Question answering

This example searches the WikiCity objects to answer the question, "When was the London Olympics?" Update your code from the last example, and try it out yourself.

Python

ask = {
  "question": "When was the London Olympics?",
  "properties": ["wiki_summary"]
}

res = (
  client.query
  .get("WikiCity", [
      "city_name",
      "_additional {answer {hasAnswer property result} }"
  ])
  .with_ask(ask)
  .with_limit(1)
  .do()
)

print(json.dumps(res, indent=2))

Expected output

{
  "data": {
    "Get": {
      "WikiCity": [
        {
          "_additional": {
            "answer": {
              "hasAnswer": true,
              "property": "wiki_summary",
              "result": " 2012"
            }
          },
          "city_name": "London"
        }
      ]
    }
  }
}

Exercise

Try varying the question from, "When was the London Olympics?" to another, city-related, question. What do you see?

Try to see what types of questions work better than others. Do you notice any patterns?

Generative search

This example also searches the WikiCity objects, but this one uses the Weaviate generative-openai module to transform the results. In this case, the module produces tweets about cities in Southeast Asia.

Update your demo code once again, and try it out:

Python

res = client.query.get(
    "WikiCity", ["city_name", "wiki_summary"]
).with_near_text({
    "concepts": ["Popular Southeast Asian tourist destination"]
}).with_limit(3).with_generate(
    single_prompt=\
    "Write a tweet with a potentially surprising fact from {wiki_summary}"
).do()

for city_result in res["data"]["Get"]["WikiCity"]:
    print(json.dumps(city_result["_additional"], indent=2))

Expected output

{
  "generate": {
    "error": null,
    "singleResult": " #FunFact: Bangkok is the world's most visited city, with over 22 million visitors in 2019! #Bangkok #Thailand #Travel"
  }
}
{
  "generate": {
    "error": null,
    "singleResult": "Did you know that Ho Chi Minh City is home to many multinational companies and generates nearly a quarter of Vietnam's total GDP? #HCMC #Vietnam #Economy"
  }
}
{
  "generate": {
    "error": null,
    "singleResult": "Surprising fact: Singapore is the only country in Asia with a AAA sovereign credit rating from all major rating agencies. #Singapore #AAA #CreditRating"
  }
}

Exercise

Try varying the prompt from:

"Write a tweet with a potentially surprising fact from {wiki_summary}"

What happens if you remove {wiki_summary}?

Review

Review exercise

Question

Which of the following is not true about the Weaviate API?

Question

What can't Weaviate clients do?

Key takeaways

Weaviate uses two API types, REST and GraphQL. REST is used for CRUD operations and metadata, while GraphQL is used for data searches, retrieving data objects, and exploring vector spaces.
Client libraries are used to access both REST and GraphQL APIs, providing a convenient way to interact with Weaviate instances.
You have connected to a demo Weaviate instance to run vector searches, question-answering queries, and generative searches.

Questions and feedback

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

Preparation​

Overview​

Client instantiation​

Try it out!​

Weaviate API and the client​

Available APIs​

Access the REST API​

Example 1: REST vs client requests​

Example 2: GraphQL vs client requests​

Running queries​

Connect to our demo instance​

Vector searches​

Question answering​

Generative search​

Review​

Review exercise​

Key takeaways​

Questions and feedback​

Preparation

Overview

Client instantiation

Try it out!

Weaviate API and the client

Available APIs

Access the REST API

Example 1: REST vs client requests

Example 2: GraphQL vs client requests

Running queries

Connect to our demo instance

Vector searches

Question answering

Generative search

Review

Review exercise

Key takeaways

Questions and feedback