In this lesson, you will perform semantic searches in practice.

We covered the concept of semantic searches briefly in another course (Key Concepts & Architecture). Briefly, they identify similar objects by their meaning, using vector similarity.

Here, you will see a practical example of how to perform semantic searches using the Python client and the previously ingested "Movies" data.

Code

This example finds objects in "Movies" most similar to the query "dystopian future", and prints out the title and release year of the top 5 matches.

import weaviate
from weaviate.classes.query import Filter, MetadataQuery
import os


# Instantiate your client (not shown). e.g.:
# client = weaviate.connect_to_weaviate_cloud(...) or
# client = weaviate.connect_to_local(...)

# Configure collection object
movies = client.collections.use("Movies")

# Perform query
response = movies.query.near_text(
    query="dystopian future",
    limit=5,
    return_metadata=MetadataQuery(distance=True)
)

# Inspect the response
for o in response.objects:
    print(o.properties["title"], o.properties["release_date"].year)  # Print the title and release year (note the release date is a datetime object)
    print(f"Distance to query: {o.metadata.distance:.3f}\n")  # Print the distance of the object from the query

client.close()

  API docs

Single vs multiple object vectors

In this course, the collection is configured with one vector per object. It is also possible to attach multiple vectors to a single object, allowing for choices in how to search the object.

When using multiple vectors, you must specify which vector to use for the search by setting the target_vector parameter in the query.

Explain the code

The search results are based on vector similarity between the query and the database object.

The limit parameter sets the maximum number of results to return.

The return_metadata parameter takes an instance of the MetadataQuery class to set metadata to return in the search results. The current query returns the vector distance to the query.

Default data returned

Unless explicitly specified, each query returns matching objects, with object UUIDs and all properties excluding BLOB data types. To minimize unnecessary data transfer, BLOB properties, object vectors and search metadata such search scores or distances are not included unless requested.

Example results

In Time 2011
Distance to query: 0.179

Gattaca 1997
Distance to query: 0.180

I, Robot 2004
Distance to query: 0.182

Mad Max: Fury Road 2015
Distance to query: 0.190

The Maze Runner 2014
Distance to query: 0.193

Response object

The returned object is a custom class instance. Its objects attribute contains a list of search results, where each result is also a custom class instance.

Each returned object includes:

• All properties and its UUID by default (excluding blob data types)
• No additional information by default (references, metadata, vectors, etc.)

What's next?

Semantic searches are a powerful way to find relevant data in Weaviate. In the next lesson, you will learn how to use keyword searches to reward exact matches, and hybrid searches that combine semantic and keyword searches.