Skip to main content
Go to documentation:
⌘U
Weaviate Database

Develop AI applications using Weaviate's APIs and tools

Deploy

Deploy, configure, and maintain Weaviate Database

Query Agent

Run agentic search over your Weaviate Cloud collections

Weaviate Cloud

Manage and scale Weaviate in the cloud

Engram

Persistent memory for LLM agents and applications

Additional resources

Integrations
Weaviate Academy

Need help?

Weaviate LogoAsk AI Assistant⌘K
Support
Community Forum
Contributor guide

Multiple target vectors

In a multi-target vector search, Weaviate searches multiple target vector spaces concurrently. These results are combined using a "join strategy" to produce a single set of search results.

There are multiple ways to specify the target vectors and query vectors, such as:

Multi-target vector search is available for near_xxx queries (from v1.26), as well as hybrid queries (from v1.27).

Available join strategies.​

  • minimum (default) Use the minimum of all vector distances.
  • sum Use the sum of the vector distances.
  • average Use the average of the vector distances.
  • manual weights Use the sum of weighted distances, where the weight is provided for each target vector.
  • relative score Use the sum of weighted normalized distances, where the weight is provided for each target vector.

Specify target vector names only​

As a minimum, specify the target vector names as an array of named vectors. This will use the default join strategy.

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.
from weaviate.classes.query import MetadataQuery

collection = client.collections.use("JeopardyTiny")

response = collection.query.near_text(
query="a wild animal",
limit=2,
target_vector=["jeopardy_questions_vector", "jeopardy_answers_vector"], # Specify the target vectors
return_metadata=MetadataQuery(distance=True)
)

for o in response.objects:
print(o.properties)
return_metadata=MetadataQuery(distance=True)
var jeopardy, result;

jeopardy = client.collections.use('JeopardyTiny');

result = await jeopardy.query.nearText('a wild animal', {
limit: 2,
targetVector: ['jeopardy_questions_vector', 'jeopardy_answers_vector'],
returnMetadata: ['distance'],
});

result.objects.forEach((item) => {
console.log(JSON.stringify(item.properties, null, 2));
console.log(JSON.stringify(item.metadata?.distance, null, 2));
});
concepts := []string{"a wild animal"}
nearText := client.GraphQL().NearTextArgBuilder().
WithConcepts(concepts).
WithTargetVectors("jeopardy_questions_vector", "jeopardy_answers_vector")

ctx := context.Background()

result, err := client.GraphQL().Get().
WithClassName(className).
WithFields(graphql.Field{Name: "question"}, graphql.Field{Name: "answer"}).
WithNearText(nearText).
Do(ctx)
Complete code
package main

import (
"context"
"fmt"
"os"

"github.com/weaviate/weaviate-go-client/v5/weaviate"
"github.com/weaviate/weaviate-go-client/v5/weaviate/graphql"
)

func main() {
cfg := weaviate.Config{
Host: "localhost:8080",
Scheme: "http",
Headers: map[string]string{
"X-Openai-Api-Key": os.Getenv("OPENAI_API_KEY"),
},
}

client, err := weaviate.NewClient(cfg)
if err != nil {
panic(err)
}

className := "JeopardyTiny"
concepts := []string{"a wild animal"}
nearText := client.GraphQL().NearTextArgBuilder().
WithConcepts(concepts).
WithTargetVectors("jeopardy_questions_vector", "jeopardy_answers_vector")

ctx := context.Background()

result, err := client.GraphQL().Get().
WithClassName(className).
WithFields(graphql.Field{Name: "question"}, graphql.Field{Name: "answer"}).
WithNearText(nearText).
Do(ctx)

if err != nil {
panic(err)
}

fmt.Printf("%+v", result)
}
jeopardy := client.Collections.Use("JeopardyTiny")
response, err := jeopardy.Query.NearText(ctx, query.NearText{
Concepts: []string{"a wild animal"},
// Minimum is the default join strategy when combining target vectors.
Target: query.Min([]query.VectorName{
"jeopardy_questions_vector",
"jeopardy_answers_vector",
}),
Limit: 2,
ReturnMetadata: query.ReturnMetadata{Distance: true},
})
if err != nil {
// handle error
panic(err)
}
for _, obj := range response.Objects {
fmt.Printf("%v\n", obj.Properties)
}
CollectionHandle<Map<String, Object>> collection =
client.collections.use(COLLECTION_NAME);

var response = collection.query.nearText(
// In Java, a plain list of target vectors implies an "average" strategy
Target.average("a wild animal", "jeopardy_questions_vector",
"jeopardy_answers_vector"),
q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(o.properties()));
System.out.println("Distance: " + o.queryMetadata().distance());
}
var collection = client.Collections.Use(CollectionName);

var response = await collection.Query.NearText(
query =>
query(["a wild animal"])
.TargetVectorsMinimum("jeopardy_questions_vector", "jeopardy_answers_vector"), // Specify the target vectors
limit: 2,
returnMetadata: MetadataOptions.Distance
);

foreach (var o in response.Objects)
{
Console.WriteLine(JsonSerializer.Serialize(o.Properties));
Console.WriteLine(o.Metadata.Distance);
}

Specify query vectors​

You can specify multiple query vectors in the search query with a nearVector search. This allows use of a different query vector for each corresponding target vector.

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.
from weaviate.classes.query import MetadataQuery

collection = client.collections.use("JeopardyTiny")

response = collection.query.near_vector(
# Specify the query vectors for each target vector
near_vector={
"jeopardy_questions_vector": v1,
"jeopardy_answers_vector": v2,
},
limit=2,
target_vector=["jeopardy_questions_vector", "jeopardy_answers_vector"], # Specify the target vectors
return_metadata=MetadataQuery(distance=True)
)

for o in response.objects:
print(o.properties)
return_metadata=MetadataQuery(distance=True)
var jeopardy, result;

jeopardy = client.collections.use('JeopardyTiny');

result = await jeopardy.query.nearVector({
'jeopardy_questions_vector': v1,
'jeopardy_answers_vector': v2
}, {
limit: 2,
targetVector: ['jeopardy_questions_vector', 'jeopardy_answers_vector'],
returnMetadata: ['distance'],
});

result.objects.forEach((item) => {
console.log(JSON.stringify(item.properties, null, 2));
console.log(JSON.stringify(item.metadata?.distance, null, 2));
});
// v1 and v2 are []float32 query vectors
jeopardy := client.Collections.Use("JeopardyTiny")
response, err := jeopardy.Query.NearVector(ctx, query.NearVector{
// Pair each named target vector with its own query vector.
Target: query.Min([]types.Vector{
{Name: "jeopardy_questions_vector", Single: v1},
{Name: "jeopardy_answers_vector", Single: v2},
}),
Limit: 2,
ReturnMetadata: query.ReturnMetadata{Distance: true},
})
if err != nil {
// handle error
panic(err)
}
for _, obj := range response.Objects {
fmt.Printf("%v\n", obj.Properties)
}
var response = collection.query.nearVector(
// Specify the query vectors for each target vector using Target objects
// The default combination strategy is "average"
Target.average(Target.vector("jeopardy_questions_vector", v1),
Target.vector("jeopardy_answers_vector", v2)),
q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(o.properties()));
System.out.println("Distance: " + o.queryMetadata().distance());
}
var response = await collection.Query.NearVector(
// Specify the query vectors for each target vector
vectors: new Vectors
{
{ "jeopardy_questions_vector", v1 },
{ "jeopardy_answers_vector", v2 },
},
limit: 2,
returnMetadata: MetadataOptions.Distance
);

foreach (var o in response.Objects)
{
Console.WriteLine(JsonSerializer.Serialize(o.Properties));
Console.WriteLine(o.Metadata.Distance);
}

You can also specify the query vectors as an array of vectors. The array will be parsed according to the order of the specified target vectors.

Specify array(s) of query vectors​

You can also specify the same target vector multiple times with different query vectors. In other words, you can use multiple query vectors for the same target vector.

The query vectors in this case are specified as an array of vectors. There are multiple ways to specify the target vectors in this case:

Target vector names only​

The target vectors can be specified as an array as shown here.

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.
from weaviate.classes.query import MetadataQuery

collection = client.collections.use("JeopardyTiny")

response = collection.query.near_vector(
# Specify the query vectors for each target vector
near_vector={
"jeopardy_questions_vector": v1,
"jeopardy_answers_vector": [v2, v3]
},
limit=2,
# Specify the target vectors as a list
target_vector=[
"jeopardy_questions_vector",
"jeopardy_answers_vector",
],
return_metadata=MetadataQuery(distance=True)
)

for o in response.objects:
print(o.properties)
return_metadata=MetadataQuery(distance=True)
var jeopardy, result;

jeopardy = client.collections.use('JeopardyTiny');

result = await jeopardy.query.nearVector({
// Specify the query vectors for each target vector. where v1, v2.. are vectors
'jeopardy_questions_vector': v1,
'jeopardy_answers_vector': [v2, v3]
}, {
limit: 2,
// Specify the target vectors as a list
targetVector: ['jeopardy_questions_vector', 'jeopardy_answers_vector'],
returnMetadata: ['distance'],
});

result.objects.forEach((item) => {
console.log(JSON.stringify(item.properties, null, 2));
console.log(JSON.stringify(item.metadata?.distance, null, 2));
});
// v1, v2 and v3 are []float32 query vectors
jeopardy := client.Collections.Use("JeopardyTiny")
response, err := jeopardy.Query.NearVector(ctx, query.NearVector{
// A target vector name may appear more than once, each with its own vector.
Target: query.Min([]types.Vector{
{Name: "jeopardy_questions_vector", Single: v1},
{Name: "jeopardy_answers_vector", Single: v2},
{Name: "jeopardy_answers_vector", Single: v3},
}),
Limit: 2,
ReturnMetadata: query.ReturnMetadata{Distance: true},
})
if err != nil {
// handle error
panic(err)
}
for _, obj := range response.Objects {
fmt.Printf("%v\n", obj.Properties)
}
var responseV1 = collection.query.nearVector(
// Pass multiple Target.vector objects with the same name
// The default combination strategy is "average"
Target.average(Target.vector("jeopardy_questions_vector", v1),
Target.vector("jeopardy_answers_vector", v2),
Target.vector("jeopardy_answers_vector", v3)),
q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : responseV1.objects()) {
System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(o.properties()));
System.out.println("Distance: " + o.queryMetadata().distance());
}
var response = await collection.Query.NearVector(
// Use NearVectorInput to pass multiple vectors naturally
vectors: v =>
v.TargetVectorsSum(
("jeopardy_questions_vector", v1),
("jeopardy_answers_vector", v2),
("jeopardy_answers_vector", v3)
),
limit: 2,
returnMetadata: MetadataOptions.Distance
);

Target vectors and weights​

If you want to provide weights for each target vector you can do it as shown here.

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.
from weaviate.classes.query import TargetVectors, MetadataQuery

collection = client.collections.use("JeopardyTiny")

response = collection.query.near_vector(
# Specify the query vectors for each target vector
near_vector={
"jeopardy_questions_vector": v1,
"jeopardy_answers_vector": [v2, v3]
},
limit=2,
# Specify the target vectors and weights
target_vector=TargetVectors.manual_weights({
"jeopardy_questions_vector": 10,
"jeopardy_answers_vector": [30, 30], # Matches the order of the vectors above
}),
return_metadata=MetadataQuery(distance=True)
)

for o in response.objects:
print(o.properties)
return_metadata=MetadataQuery(distance=True)
var jeopardy, result;

jeopardy = client.collections.use('JeopardyTiny');

result = await jeopardy.query.nearVector({
'jeopardy_questions_vector': v1,
'jeopardy_answers_vector': [v2, v3]
}, {
limit: 2,
// Specify the target vectors as a list
targetVector: jeopardy.multiTargetVector.manualWeights({
"jeopardy_questions_vector": 10,
"jeopardy_answers_vector": [30, 30], // Matches the order of the vectors above
}),
returnMetadata: ['distance'],
});

result.objects.forEach((item) => {
console.log(JSON.stringify(item.properties, null, 2));
console.log(JSON.stringify(item.metadata?.distance, null, 2));
});
// v1, v2 and v3 are []float32 query vectors
jeopardy := client.Collections.Use("JeopardyTiny")
response, err := jeopardy.Query.NearVector(ctx, query.NearVector{
// Weight each query vector; repeated targets are weighted independently.
Target: query.ManualWeights([]query.WeightedVector[types.Vector]{
query.Weighted(types.Vector{Name: "jeopardy_questions_vector", Single: v1}, 10),
query.Weighted(types.Vector{Name: "jeopardy_answers_vector", Single: v2}, 30),
query.Weighted(types.Vector{Name: "jeopardy_answers_vector", Single: v3}, 30),
}),
Limit: 2,
ReturnMetadata: query.ReturnMetadata{Distance: true},
})
if err != nil {
// handle error
panic(err)
}
for _, obj := range response.Objects {
fmt.Printf("%v\n", obj.Properties)
}
var responseV2 = collection.query.nearVector(
// Specify weights for each vector
Target.manualWeights(
Target.vector("jeopardy_questions_vector", 10f, v1),
Target.vector("jeopardy_answers_vector", 30f, v2),
Target.vector("jeopardy_answers_vector", 30f, v3) // Weights match the vectors
),
q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : responseV2.objects()) {
System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(o.properties()));
System.out.println("Distance: " + o.queryMetadata().distance());
}
var responseV2 = await collection.Query.NearVector(
vectors: v =>
v.TargetVectorsManualWeights(
("jeopardy_questions_vector", 10, v1),
("jeopardy_answers_vector", 30, v2),
("jeopardy_answers_vector", 30, v3)
),
limit: 2,
returnMetadata: MetadataOptions.Distance
);

Specify target vector names and join strategy​

Specify target vectors as an array of named vectors and how to join the result sets.

The sum, average, minimum join strategies only require the name of the strategy and the target vectors.

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.
from weaviate.classes.query import TargetVectors, MetadataQuery

collection = client.collections.use("JeopardyTiny")

response = collection.query.near_text(
query="a wild animal",
limit=2,
target_vector=TargetVectors.average(["jeopardy_questions_vector", "jeopardy_answers_vector"]), # Specify the target vectors and the join strategy
# .sum(), .minimum(), .manual_weights(), .relative_score() also available
return_metadata=MetadataQuery(distance=True)
)

for o in response.objects:
print(o.properties)
print(o.metadata.distance)
var jeopardy, result;

jeopardy = client.collections.use('JeopardyTiny');

result = await jeopardy.query.nearText('a wild animal', {
limit: 2,
targetVector: jeopardy.multiTargetVector.average(['jeopardy_questions_vector', 'jeopardy_answers_vector']),
returnMetadata: ['distance'],
});

result.objects.forEach((item) => {
console.log(JSON.stringify(item.properties, null, 2));
console.log(JSON.stringify(item.metadata?.distance, null, 2));
});
jeopardy := client.Collections.Use("JeopardyTiny")
response, err := jeopardy.Query.NearText(ctx, query.NearText{
Concepts: []string{"a wild animal"},
// query.Sum, query.Min, query.ManualWeights, and query.RelativeScore
// are also available.
Target: query.Average([]query.VectorName{
"jeopardy_questions_vector",
"jeopardy_answers_vector",
}),
Limit: 2,
ReturnMetadata: query.ReturnMetadata{Distance: true},
})
if err != nil {
// handle error
panic(err)
}
for _, obj := range response.Objects {
fmt.Printf("%v\n", obj.Properties)
}
CollectionHandle<Map<String, Object>> collection =
client.collections.use(COLLECTION_NAME);

var response = collection.query.nearText(
Target.average("a wild animal", "jeopardy_questions_vector",
"jeopardy_answers_vector"), // Specify the target vectors and the join strategy
// .sum(), .min(), .manualWeights(), .relativeScore() also available
q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(o.properties()));
System.out.println("Distance: " + o.queryMetadata().distance());
}
var collection = client.Collections.Use(CollectionName);

var response = await collection.Query.NearText(
query =>
query(["a wild animal"])
// Specify the target vectors and the join strategy
// Available: Sum, Minimum, Average, ManualWeights, RelativeScore
.TargetVectorsAverage("jeopardy_questions_vector", "jeopardy_answers_vector"),
limit: 2,
returnMetadata: MetadataOptions.Distance
);

foreach (var o in response.Objects)
{
Console.WriteLine(JsonSerializer.Serialize(o.Properties));
Console.WriteLine(o.Metadata.Distance);
}

Weight raw vector distances​

Search by sums of weighted, raw distances to each target vector.

The weighting in detail

Each distance between the query vector and the target vector is multiplied by the specified weight, then the resulting weighted distances are summed for each object to produce a combined distance. The search results are sorted by this combined distance.

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.
from weaviate.classes.query import TargetVectors, MetadataQuery

collection = client.collections.use("JeopardyTiny")

response = collection.query.near_text(
query="a wild animal",
limit=2,
target_vector=TargetVectors.manual_weights({
"jeopardy_questions_vector": 10,
"jeopardy_answers_vector": 50
}),
return_metadata=MetadataQuery(distance=True)
)

for o in response.objects:
print(o.properties)
print(o.metadata.distance)
var jeopardy, result;

jeopardy = client.collections.use('JeopardyTiny');

result = await jeopardy.query.nearText('a wild animal', {
limit: 2,
targetVector: jeopardy.multiTargetVector.manualWeights({
jeopardy_questions_vector: 10,
jeopardy_answers_vector: 50,
}),
returnMetadata: ['distance'],
});

result.objects.forEach((item) => {
console.log(JSON.stringify(item.properties, null, 2));
console.log(JSON.stringify(item.metadata?.distance, null, 2));
});
jeopardy := client.Collections.Use("JeopardyTiny")
response, err := jeopardy.Query.NearText(ctx, query.NearText{
Concepts: []string{"a wild animal"},
Target: query.ManualWeights([]query.WeightedVector[query.VectorName]{
query.Weighted(query.VectorName("jeopardy_questions_vector"), 10),
query.Weighted(query.VectorName("jeopardy_answers_vector"), 50),
}),
Limit: 2,
ReturnMetadata: query.ReturnMetadata{Distance: true},
})
if err != nil {
// handle error
panic(err)
}
for _, obj := range response.Objects {
fmt.Printf("%v\n", obj.Properties)
}
CollectionHandle<Map<String, Object>> collection =
client.collections.use(COLLECTION_NAME);

var response = collection.query.nearText(
Target.manualWeights("a wild animal",
Target.weight("jeopardy_questions_vector", 10f),
Target.weight("jeopardy_answers_vector", 50f)),
q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(o.properties()));
System.out.println("Distance: " + o.queryMetadata().distance());
}
var collection = client.Collections.Use(CollectionName);

var response = await collection.Query.NearText(
query =>
query(["a wild animal"])
.TargetVectorsManualWeights(
("jeopardy_questions_vector", 10),
("jeopardy_answers_vector", 50)
),
limit: 2,
returnMetadata: MetadataOptions.Distance
);

foreach (var o in response.Objects)
{
Console.WriteLine(JsonSerializer.Serialize(o.Properties));
Console.WriteLine(o.Metadata.Distance);
}

Weight normalized vector distances​

Search by sums of weighted, normalized distances to each target vector.

The weighting in detail

Each distance is normalized against other results for that target vector. Each normalized distance between the query vector and the target vector is multiplied by the specified weight. The resulting weighted distances are summed for each object to produce a combined distance. The search results are sorted by this combined distance.

For a more detailed explanation of how scores are normalized, see the blog post on hybrid relative score fusion

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.
from weaviate.classes.query import TargetVectors, MetadataQuery

collection = client.collections.use("JeopardyTiny")

response = collection.query.near_text(
query="a wild animal",
limit=2,
target_vector=TargetVectors.relative_score({
"jeopardy_questions_vector": 10,
"jeopardy_answers_vector": 10
}),
return_metadata=MetadataQuery(distance=True)
)

for o in response.objects:
print(o.properties)
print(o.metadata.distance)
var jeopardy, result;

jeopardy = client.collections.use('JeopardyTiny');

result = await jeopardy.query.nearText('a wild animal', {
limit: 2,
targetVector: jeopardy.multiTargetVector.relativeScore({
jeopardy_questions_vector: 10,
jeopardy_answers_vector: 10,
}),
returnMetadata: ['distance'],
});

result.objects.forEach((item) => {
console.log(JSON.stringify(item.properties, null, 2));
console.log(JSON.stringify(item.metadata?.distance, null, 2));
});
jeopardy := client.Collections.Use("JeopardyTiny")
response, err := jeopardy.Query.NearText(ctx, query.NearText{
Concepts: []string{"a wild animal"},
Target: query.RelativeScore([]query.WeightedVector[query.VectorName]{
query.Weighted(query.VectorName("jeopardy_questions_vector"), 10),
query.Weighted(query.VectorName("jeopardy_answers_vector"), 10),
}),
Limit: 2,
ReturnMetadata: query.ReturnMetadata{Distance: true},
})
if err != nil {
// handle error
panic(err)
}
for _, obj := range response.Objects {
fmt.Printf("%v\n", obj.Properties)
}
CollectionHandle<Map<String, Object>> collection =
client.collections.use(COLLECTION_NAME);

var response = collection.query.nearText(
Target.relativeScore("a wild animal",
Target.weight("jeopardy_questions_vector", 10f),
Target.weight("jeopardy_answers_vector", 10f)),
q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
System.out.println(objectMapper.writerWithDefaultPrettyPrinter()
.writeValueAsString(o.properties()));
System.out.println("Distance: " + o.queryMetadata().distance());
}
var collection = client.Collections.Use(CollectionName);

var response = await collection.Query.NearText(
query =>
query(["a wild animal"])
.TargetVectorsRelativeScore(
("jeopardy_questions_vector", 10),
("jeopardy_answers_vector", 10)
),
returnMetadata: MetadataOptions.Distance
);

foreach (var o in response.Objects)
{
Console.WriteLine(JsonSerializer.Serialize(o.Properties));
Console.WriteLine(o.Metadata.Distance);
}

Questions and feedback​