Getting hands-on

Preparation

Obtain a free trial OpenAI API key

This section includes queries using the OpenAI inference endpoint. So, we recommend obtaining an OpenAI account, and obtaining a free API key which should be sufficient for all of the below.

Overview

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

Client instantiation

A client object can be instantiated for convenient access to your instance of Weaviate. You can set the following parameters:

Host URL (required):

This is the location of your Weaviate instance, such as https://example.weaviate.network

Authentication information (optional)

If authentication is enabled, you MUST provide your authentication information here. Otherwise the Weaviate instance will not provide access.

Additional headers (optional)

You can provide additional headers here. This is used to provide API keys for inference services such as Cohere, Hugging Face or OpenAI.

note

Parameter names may vary across libraries

Putting it together, a client can be instantiated as below:

Python

import weaviate

# Only if authentication enabled; assuming API key authentication
auth_config = weaviate.AuthApiKey(api_key="YOUR-WEAVIATE-API-KEY")  # Replace w/ 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
    }
)

API keys

In your own code, you would only need to specify the API keys for the service(s) that you are using.

Try it out

Now, try running the below, making sure to replace the Weaviate URL and the API key with those from your WCS instance.

Python

import weaviate
import json

auth_config = weaviate.AuthApiKey(api_key="YOUR-WEAVIATE-API-KEY")  # Replace w/ 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; more specifically to the meta REST endpoint. The Weaviate API allows you to do quite a bit - take a look.

Weaviate API and the client

Available APIs

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

REST vs GraphQL APIs

The REST API is used to:

Interact with Weaviate for CRUD (Create, Read, Update and Delete) operations, and
To obtain metadata about the database.

The GraphQL API is used to:

Interact with Weaviate for data searches.
For example, it can be used to retrieve data objects, aggregate information, and explore vector spaces.

You will learn about them 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 API.

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.

Accessing the REST API

Both REST and GraphQL APIs can be accessed using client libraries.

Take the commands shown below. In both examples, the code in each tab are functionally the same:

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

We will connect to a demo Weaviate instance containing data, and run queries ourselves. The instance has these details:

Demo instance details

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

With these details see if you can:

Instantiate a Weaviate client, and
Check that it works 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.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

Try running the following query. This will search the WikiCity objects for those closest to the specified text, which is in this case "Major European city".

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

The below example will search the WikiCity objects to look for an answer to the question "When was the London Olympics?". 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

The below example will search the WikiCity objects, and then transform the results through the generative-openai module. Try it out:

Python

res = client.query.get(
    "WikiCity", ["city_name", "wiki_summary"]
).with_near_text({
    "concepts": ["Popular South-East 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}" to another. (What happens if you remove {wiki_summary}?)

Review

Review exercise

Question

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

Question

Weaviate clients cannot do which of the following?

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.

Preparation​

Overview​

Client instantiation​

Host URL (required):​

Authentication information (optional)​

Additional headers (optional)​

Try it out​

Weaviate API and the client​

Available APIs​

Accessing 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​

Preparation

Overview

Client instantiation

Host URL (required):

Authentication information (optional)

Additional headers (optional)

Try it out

Weaviate API and the client

Available APIs

Accessing 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