Voozh

This page covers the search operators that can be used in queries, such as vector search operators (nearText, nearVector, nearObject, etc), keyword search operator (bm25), hybrid search operator (hybrid).

Only one search operator can be added to queries on the collection level.

Operator availability

Built-in operators

These operators are available in all Weaviate instances regardless of configuration.

Module-specific operators

Module-specific search operators are made available in certain Weaviate modules.

By adding relevant modules, you can use the following operators:

Vector search operators

nearXXX operators allow you to find data objects based on their vector similarity to the query. They query can be a raw vector (nearVector) or an object UUID (nearObject).

If the appropriate vectorizer model is enabled, a text query (nearText), an image (nearImage), or another media input may be be used as the query.

All vector search operators can be used with a certainty or distance threshold specified, as well as a limit operator or an autocut operator to specify the desired similarity or distance between the query and the results

nearVector

nearVector finds data objects closest to an input vector.

Variables

Variable	Required	Type	Description
`vector`	yes	`[float]`	This variable takes a vector embedding in the form of an array of floats. The array should have the same length as the vectors in this collection.
`distance`	no	`float`	The maximum allowed distance to the provided search input. Cannot be used together with the `certainty` variable. The interpretation of the value of the distance field depends on the distance metric used.
`certainty`	no	`float`	Normalized Distance between the result item and the search vector. Normalized to be between 0 (perfect opposite) and 1 (identical vectors). Can't be used together with the `distance` variable.

Example

👁 Image

👁 py docs
API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
 collection = client.collections.use("Article")

 response = collection.query.near_vector(
 near_vector=query_vector,
 distance=0.7,
 limit=5,
)

for o in response.objects:
print(o.properties)

finally:
 client.close()

nearObject

nearVector finds data objects closest to an existing object in the same collection. The object is typically specified by its UUID.

Note: You can specify an object's id or beacon in the argument, along with a desired certainty.
Note that the first result will always be the object used for search.

Variables

Variable	Required	Type	Description
`id`	yes	`UUID`	Data object identifier in the uuid format.
`beacon`	no	`url`	Data object identifier in the beacon URL format. E.g., `weaviate://<hostname>/<kind>/id`.
`distance`	no	`float`	The maximum allowed distance to the provided search input. Cannot be used together with the `certainty` variable. The interpretation of the value of the distance field depends on the distance metric used.
`certainty`	no	`float`	Normalized Distance between the result item and the search vector. Normalized to be between 0 (perfect opposite) and 1 (identical vectors). Can't be used together with the `distance` variable.

Example

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
 collection = client.collections.use("Article")

 response = collection.query.near_object(
 near_object=object_id,
 distance=0.6,
 limit=5,
)

for o in response.objects:
print(o.properties)

finally:
 client.close()

nearText

The nearText operator finds data objects based on their vector similarity to a natural language query.

This operator is enabled if a compatible vectorizer module is configured for the collection. Compatible vectorizer modules are:

Any text2vec module
Any multi2vec module

Variables

Variable	Required	Type	Description
`concepts`	yes	`[string]`	An array of strings that can be natural language queries, or single words. If multiple strings are used, a centroid is calculated and used. Learn more about how the concepts are parsed here.
`distance`	no	`float`	The maximum allowed distance to the provided search input. Cannot be used together with the `certainty` variable. The interpretation of the value of the distance field depends on the distance metric used.
`certainty`	no	`float`	Normalized Distance between the result item and the search vector. Normalized to be between 0 (perfect opposite) and 1 (identical vectors). Can't be used together with the `distance` variable.
`autocorrect`	no	`boolean`	Autocorrect input text values. Requires the `text-spellcheck` module to be present & enabled.
`moveTo`	no	`object{}`	Move your search term closer to another vector described by keywords
`moveTo{concepts}`	no	`[string]`	An array of strings - natural language queries or single words. If multiple strings are used, a centroid is calculated and used.
`moveTo{objects}`	no	`[UUID]`	Object IDs to move the results to. This is used to "bias" NLP search results into a certain direction in vector space.
`moveTo{force}`	no	`float`	The force to apply to a particular movement. Must be between 0 and 1 where 0 is equivalent to no movement and 1 is equivalent to largest movement possible.
`moveAwayFrom`	no	`object{}`	Move your search term away from another vector described by keywords
`moveAwayFrom{concepts}`	no	`[string]`	An array of strings - natural language queries or single words. If multiple strings are used, a centroid is calculated and used.
`moveAwayFrom{objects}`	no	`[UUID]`	Object IDs to move the results from. This is used to "bias" NLP search results into a certain direction in vector space.
`moveAwayFrom{force}`	no	`float`	The force to apply to a particular movement. Must be between 0 and 1 where 0 is equivalent to no movement and 1 is equivalent to largest movement possible.

Example I

This example shows an example usage the nearText operator, including how to bias results towards another search query.

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
from weaviate.classes.query import Move
import os

client = weaviate.connect_to_local()

try:
 publications = client.collections.use("Publication")

 response = publications.query.near_text(
 query="fashion",
 distance=0.6,
 move_to=Move(force=0.85, concepts="haute couture"),
 move_away=Move(force=0.45, concepts="finance"),
 return_metadata=wvc.query.MetadataQuery(distance=True),
 limit=2
)

for o in response.objects:
print(o.properties)
print(o.metadata)

finally:
 client.close()

Example II

You can also bias results toward other data objects. For example, in this query, we move our query about "travelling in asia", towards an article on food.

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
 collection = client.collections.use("Article")

 response = collection.query.near_text(
 query="travelling in Asia",
 certainty=0.7,
 move_to=wvc.query.Move(
 force=0.75,
 objects="c4209549-7981-3699-9648-61a78c2124b9"
),
 return_metadata=wvc.query.MetadataQuery(certainty=True),
 limit=5,
)

for o in response.objects:
print(o.properties)
print(o.metadata.certainty)

finally:
 client.close()

Additional information

Concept parsing

A nearText query will interpret each term in an array input as distinct strings to be vectorized. If multiple strings are passed, the query vector will be an average vector of the individual string vectors.

["New York Times"] = one vector position is determined based on the occurrences of the words
["New", "York", "Times"] = all concepts have a similar weight.
["New York", "Times"] = a combination of the two above.

A practical example would be: concepts: ["beatles", "John Lennon"]

Semantic Path

Only available in txt2vec-contextionary module

The semantic path returns an array of concepts from the query to the data object. This allows you to see which steps Weaviate took and how the query and data object are interpreted.

Property	Description
`concept`	the concept that is found in this step.
`distanceToNext`	the distance to the next step (null for the last step).
`distanceToPrevious`	this distance to the previous step (null for the first step).
`distanceToQuery`	the distance of this step to the query.
`distanceToResult`	the distance of the step to this result.

Note: Building a semantic path is only possible if a nearText: {} operator is set as the explore term represents the beginning of the path and each search result represents the end of the path. Since nearText: {} queries are currently exclusively possible in GraphQL, the semanticPath is therefore not available in the REST API.

Example: showing a semantic path without edges.

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
# Semantic path is not yet supported by the V4 client. Please use a raw GraphQL query instead.
 response = client.graphql_raw_query(
"""
 {
 Get {
 Publication (
 nearText:{
 concepts: ["fashion"],
 distance: 0.6,
 moveAwayFrom: {
 concepts: ["finance"],
 force: 0.45
 },
 moveTo: {
 concepts: ["haute couture"],
 force: 0.85
 }
 }
 ) {
 name
 _additional {
 semanticPath {
 path {
 concept
 distanceToNext
 distanceToPrevious
 distanceToQuery
 distanceToResult
 }
 }
 }
 }
 }
 }
 """
)

finally:
 client.close()

Multimodal search

Depending on the vectorizer module, you can use additional modalities such as images, audio, or video as the query, and retrieve corresponding, compatible objects.

Some modules, such as multi2vec-clip and multi2vec-bind allow you to search across modalities. For example, you can search for images using a text query, or search for text using an image query.

For more information, see specific module pages such as these:

hybrid

This operator allows you to combine BM25 and vector search to get a "best of both worlds" type search results set.

Variables

Variables	Required	Type	Description
`query`	yes	`string`	search query
`alpha`	no	`float`	weighting for each search algorithm, default 0.75
`vector`	no	`[float]`	optional to supply your own vector
`properties`	no	`[string]`	list of properties to limit the BM25 search to, default all text properties
`fusionType`	no	`string`	the type of hybrid fusion algorithm (available from `v1.20.0`)
`bm25SearchOperator`	no	`object`	set how many of the (bm25) query tokens must be present within a single searched property for an object to be considered a match. (available from `v1.31.0`)

Notes:
- alpha can be any number from 0 to 1, defaulting to 0.75.
  - alpha = 0 forces using a pure keyword search method (BM25)
  - alpha = 1 forces using a pure vector search method
  - alpha = 0.5 weighs the BM25 and vector methods evenly
- fusionType can be rankedFusion or relativeScoreFusion
  - rankedFusion (default) adds inverted ranks of the BM25 and vector search methods
  - relativeScoreFusion adds normalized scores of the BM25 and vector search methods

Fusion algorithms

Ranked fusion

The rankedFusion algorithm is Weaviate's original hybrid fusion algorithm.

In this algorithm, each object is scored according to its position in the results for that search (vector or keyword). The top-ranked objects in each search get the highest scores. Scores decrease going from top to least ranked. The total score is calculated by adding the rank-based scores from the vector and keyword searches.

Relative score fusion

In relativeScoreFusion the vector search and keyword search scores are scaled between 0 and 1. The highest raw score becomes 1 in the scaled scores. The lowest value is assigned 0. The remaining values are ranked between 0 and 1. The total score is a scaled sum of the normalized vector similarity and normalized BM25 scores.

For a fuller discussion of fusion methods, see this blog post

Additional metadata response

Hybrid search results are sorted by a score, derived as a fused combination of their BM25F score and nearText similarity (higher is more relevant). This score, and additionally the explainScore metadata can be optionally retrieved in the response.

Example

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
 collection = client.collections.use("Article")

 response = collection.query.hybrid(
 query="Fisherman that catches salmon",
 alpha=0.5,
 return_metadata=wvc.query.MetadataQuery(score=True, explain_score=True),
 limit=5,
)

for o in response.objects:
print(o.properties)
print(o.metadata.score)
print(o.metadata.explain_score)

finally:
 client.close()

Example with vector specified

You can optionally supply the vector query to the vector variable. This will override the query variable for the vector search component of the hybrid search.

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
 collection = client.collections.use("Article")

 response = collection.query.hybrid(
 query="Fisherman that catches salmon",
 vector=query_vector,
 alpha=0.5,
 return_metadata=wvc.query.MetadataQuery(score=True, explain_score=True),
 limit=5,
)

for o in response.objects:
print(o.properties)
print(o.metadata.score)
print(o.metadata.explain_score)

finally:
 client.close()

Hybrid with a conditional filter

A conditional (where) filter can be used with hybrid.

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
 collection = client.collections.use("Article")

 response = collection.query.hybrid(
 query="How to catch an Alaskan Pollock",
 alpha=0.5,
 filters=wvc.query.Filter.by_property("wordCount").less_than(1000),
 limit=5,
)

for o in response.objects:
print(o.properties)

finally:
 client.close()

Specify object properties for BM25 search

A hybrid operator can accept an array of strings to limit the set of properties for the BM25 component of the search. If unspecified, all text properties will be searched.

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
 collection = client.collections.use("JeopardyQuestion")

 response = collection.query.hybrid(
 query="Venus",
 alpha=0.25,
 query_properties=["question"],
 return_metadata=wvc.query.MetadataQuery(score=True),
 limit=5,
)

for o in response.objects:
print(o.properties)
print(o.metadata.score)

finally:
 client.close()

Oversearch with `relativeScoreFusion`

When relativeScoreFusion is used as the fusionType with a small search limit, a result set can be very sensitive to the limit parameter due to the normalization of the scores.

To mitigate this effect, Weaviate automatically performs a search with a higher limit (100) and then trims the results down to the requested limit.

BM25 search operator

Added in v1.31

Use bm25SearchOperator to set how many of the query tokens must be present within a single searched property for an object to be considered a match in the keyword (bm25) search portion of the hybrid search. This is useful when you want to ensure that only objects with a certain number of relevant keywords are returned.

The available options are And, or Or. With And, all of the query tokens must appear together within a single searched property; tokens spread across different properties do not match. If Or is set, an additional parameter minimumOrTokensMatch must be specified, which defines how many of the query tokens must be present within a single searched property for the object to be considered a match.

If not set, the keyword search behaves as if Or was set with a minimumOrTokensMatch of 1.

BM25

The bm25 operator performs a keyword (sparse vector) search, and uses the BM25F ranking function to score the results. BM25F (Best Match 25 with Extension to Multiple Weighted Fields) is an extended version of BM25 that applies the scoring algorithm to multiple fields (properties), producing better results.

The search is case-insensitive, and case matching does not confer a score advantage. Stop words are removed. Stemming is not supported yet.

Schema configuration

The free parameters k1 and b are configurable and optional. See the schema reference for more details.

Variables

The bm25 operator supports the following variables:

Variables	Required	Description
`query`	yes	The keyword search query.
`properties`	no	Array of properties (fields) to search in, defaulting to all properties in the collection.
`searchOperator`	no	set how many of the query tokens must be present within a single searched property for an object to be considered a match. (available from `v1.31.0`)

Boosting properties

Specific properties can be boosted by a factor specified as a number after the caret sign, for example properties: ["title^3", "summary"].

Additional metadata response

The BM25F score metadata can be optionally retrieved in the response. A higher score indicates higher relevance.

Example query

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
 collection = client.collections.use("Article")

 response = collection.query.bm25(
 query="fox",
 query_properties=["title"],
 return_metadata=wvc.query.MetadataQuery(score=True),
 limit=5,
)

for o in response.objects:
print(o.properties)
print(o.metadata.score)

finally:
 client.close()

BM25 with a conditional filter

A conditional (where) filter can be used with bm25.

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
 collection = client.collections.use("Article")

 response = collection.query.bm25(
 query="how to fish",
 return_metadata=wvc.query.MetadataQuery(score=True),
 filters=wvc.query.Filter.by_property("wordCount").less_than(1000),
 limit=5,
)

for o in response.objects:
print(o.properties)
print(o.metadata.score)

finally:
 client.close()

Search operator

Added in v1.31

Use searchOperator to set how many of the query tokens must be present within a single searched property for an object to be considered a match. This is useful when you want to ensure that only objects with a certain number of relevant keywords are returned.

If not set, the keyword search behaves as if Or was set with a minimumOrTokensMatch of 1.

ask

Enabled by the module: Question Answering.

This operator allows you to return answers to questions by running the results through a Q&A model.

Variables

Variable	Required	Type	Description
`question`	yes	`string`	The question to be answered.
`certainty`	no	`float`	Desired minimal certainty or confidence of answer to the question. The higher the value, the stricter the search becomes. The lower the value, the fuzzier the search becomes. If no certainty is set, any answer that could be extracted will be returned.
`properties`	no	`[string]`	The properties of the queries collection which contains text. If no properties are set, all are considered.
`rerank`	no	`boolean`	If enabled, the qna module will rerank the result based on the answer score. For example, if the 3rd result - as determined by the previous (semantic) search contained the most likely answer, result 3 will be pushed to position 1, etc. Supported since v1.10.0

Example

👁 Image

👁 py docs
API docs

import weaviate
import weaviate.classes as wvc
import os

client = weaviate.connect_to_local(
 headers={
"X-OpenAI-Api-Key": os.getenv("OPENAI_API_KEY")
}
)

try:
# QnA module use is not yet supported by the V4 client. Please use a raw GraphQL query instead.
 response = client.graphql_raw_query(
"""
 {
 Get {
 Article(
 ask: {
 question: "Who is the king of the Netherlands?",
 properties: ["summary"],
 },
 limit: 1
 ) {
 title
 _additional {
 answer {
 hasAnswer
 property
 result
 startPosition
 endPosition
 }
 }
 }
 }
 }
 """

finally:
 client.close()

Additional metadata response

The answer and a certainty can be retrieved.

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.

URL: https://docs.weaviate.io/weaviate/api/graphql/search-operators

⇱ Search operators | Weaviate Documentation

Additional resources

Need help?

Operator availability​

Built-in operators​

Module-specific operators​

Vector search operators​

nearVector​

Variables​

Example​

nearObject​

Variables​

Example​

nearText​

Variables​

Example I​

Example II​

Additional information​

Concept parsing​

Semantic Path​

Multimodal search​

hybrid​

Variables​

Fusion algorithms​

Ranked fusion​

Relative score fusion​

Additional metadata response​

Example​

Example with vector specified​

Hybrid with a conditional filter​

Specify object properties for BM25 search​

Oversearch with relativeScoreFusion​

BM25 search operator​

BM25​

Schema configuration​

Variables​

Additional metadata response​

Example query​

BM25 with a conditional filter​

Search operator​

ask​

Variables​

Example​

Additional metadata response​

Questions and feedback​

Operator availability

Built-in operators

Module-specific operators

Vector search operators

nearVector

Variables

Example

nearObject

Variables

Example

nearText

Variables

Example I

Example II

Additional information

Concept parsing

Semantic Path

Multimodal search

hybrid

Variables

Fusion algorithms

Ranked fusion

Relative score fusion

Additional metadata response

Example

Example with vector specified

Hybrid with a conditional filter

Specify object properties for BM25 search

Oversearch with `relativeScoreFusion`

BM25 search operator

BM25

Schema configuration

Variables

Additional metadata response

Example query

BM25 with a conditional filter

Search operator

ask

Variables

Example

Additional metadata response

Questions and feedback