Skip to main content

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.

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.

  1. Copy the client code below to a file called connection_example.py.

  2. Edit the file to use your Weaviate URL

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

  4. Run the file.

    python3 connection_example.py
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​

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

Example 2: GraphQL vs client requests​

{
  Get {
    WikiArticle {
      title
      wiki_summary
    }
  }
}

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

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:

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.