Skip to main content

Semantic search

With Weaviate, you can perform semantic searches to find similar items based on their meaning. This is done by comparing the vector embeddings of the items in the database.

Code​

This example finds entries in "Movie" based on their similarity to the query "dystopian future", and prints out the title and release year of the top 5 matches.

import weaviate
import weaviate.classes.query as wq
import os


# Instantiate your client (not shown). e.g.:
# headers = {"X-OpenAI-Api-Key": os.getenv("OPENAI_APIKEY")}  # Replace with your OpenAI API key
# client = weaviate.connect_to_weaviate_cloud(..., headers=headers) or
# client = weaviate.connect_to_local(..., headers=headers)

# Get the collection
movies = client.collections.get("Movie")

# Perform query
response = movies.query.near_text(
    query="dystopian future", limit=5, return_metadata=wq.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()
py docs  API docs

Explain the code​

The results are based on similarity of the vector embeddings between the query and the database object text. In this case, the embeddings are generated by the vectorizer module.

The limit parameter here 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.

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 an instance of a custom class. Its objects attribute is a list of search results, each object being an instance of another custom class.

Each returned object will:

  • Include all properties and its UUID by default except those with blob data types.
  • Not include any other information (e.g. references, metadata, vectors.) by default.

Questions and feedback​

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