---
title: "Vector similarity search"
description: "Vector similarity search (nearText, nearVector, nearObject) with code examples in Python, TypeScript, Go, Java, and C#."
url: https://docs.weaviate.io/weaviate/search/similarity
---

# Vector similarity search

Vector search returns the objects with most similar vectors to that of the query.

> [!TIP]
>
> **Prefer natural language queries?**
>
> The [Query Agent](https://docs.weaviate.io/weaviate/search/query-agent) translates plain English questions into optimized Weaviate queries automatically - no manual query construction needed.

## Search with text

Use the [`Near Text`](https://docs.weaviate.io/weaviate/api/graphql/search-operators#neartext) operator to find objects with the nearest vector to an input text.

**Python**

```python
from weaviate.classes.query import MetadataQuery

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.query.near_text(
    query="animals in movies",
    limit=2,
    return_metadata=MetadataQuery(distance=True)
)

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

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.query.nearText('animals in movies', {
  limit: 2,
  returnMetadata: ['distance']
})

result.objects.forEach(item => {
  console.log(JSON.stringify(item.properties, null, 2))
  console.log(item.metadata?.distance)
})
```

**Go (v5)**

```go
response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
    graphql.Field{Name: "question"},
    graphql.Field{Name: "answer"},
    graphql.Field{
      Name: "_additional",
      Fields: []graphql.Field{
        {Name: "distance"},
      },
    },
  ).
  WithNearText(client.GraphQL().NearTextArgBuilder().
    WithConcepts([]string{"animals in movies"})).
  WithLimit(2).
  Do(ctx)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
response, err := jeopardy.Query.NearText(ctx, query.NearText{
  Concepts: []string{"animals in movies"},
  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)
  if obj.Metadata.Distance != nil {
    fmt.Printf("distance: %v\n", *obj.Metadata.Distance)
  }
}
```

**Java**

```java
CollectionHandle<Map<String, Object>> jeopardy =
    client.collections.use("JeopardyQuestion");
var response = jeopardy.query.nearText(
    "animals in movies",
    q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
  System.out.println(o.properties());
  System.out.println(o.queryMetadata().distance());
}
```

**GraphQL**

```graphql
{
  Get {
    JeopardyQuestion(
      limit: 2
      nearText: {
        concepts: ["animals in movies"]
      }
    ) {
      question
      answer
      _additional {
        distance
      }
    }
  }
}
```

**C#**

```csharp
var jeopardy = client.Collections.Use("JeopardyQuestion");
var response = await jeopardy.Query.NearText(
    "animals in movies",
    limit: 2,
    returnMetadata: MetadataOptions.Distance
);

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

**Example response**

The output is like this:

```json
{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "answer": "meerkats",
          "question": "Group of mammals seen <a href=\"http://www.j-archive.com/media/1998-06-01_J_28.jpg\" target=\"_blank\">here</a>:  [like Timon in <i>The Lion King</i>]",
          "_additional": { "distance": 0.17602634 }
        },
        {
          "answer": "dogs",
          "question": "Scooby-Doo, Goofy & Pluto are cartoon versions",
          "_additional": { "distance": 0.17842108 }
        }
      ]
    }
  }
}
```

## Search with image

Use the [`Near Image`](https://docs.weaviate.io/weaviate/api/graphql/search-operators) operator to find objects with the nearest vector to an image.\
This example uses a base64 representation of an image.

**Python**

```py
base64_string="SOME_BASE_64_REPRESENTATION"

# Get the collection containing images
dogs = client.collections.use("Dog")

# Perform query
response = dogs.query.near_image(
    near_image=base64_string,
    return_properties=["breed"],
    limit=1,
    # targetVector: "vector_name" # required when using multiple named vectors
)

print(response.objects[0])

client.close()
```

**JavaScript/TypeScript**

```ts
  import { toBase64FromMedia } from '@weaviate/node';

  const myCollection = client.collections.use('Dog');
  const filePath = './images/search-image.jpg'
  const base64String = await toBase64FromMedia(file.path)

  // Perform query
  const result = await myCollection.query.nearImage(base64String, {
    returnProperties: ['breed'],
    limit: 1,
    // targetVector: 'vector_name' // required when using multiple named vectors
  })

  console.log(JSON.stringify(result.objects, null, 2));
```

**Java**

```java
String base64String = fileToBase64(QUERY_IMAGE_PATH); // This would be a real base64 string

// Get the collection containing images
CollectionHandle<Map<String, Object>> dogs = client.collections.use("Dog");

// Perform query
var response = dogs.query.nearImage(base64String,
    q -> q.returnProperties("breed").limit(1)
// targetVector: "vector_name" // required when using multiple named vectors
);

if (!response.objects().isEmpty()) {
  System.out.println(response.objects().get(0));
}
```

**C#**

```csharp
// The C# client's NearImage method takes a byte array directly.
var imageBytes = await FileToByteArray(QUERY_IMAGE_PATH);

// Get the collection containing images
var dogs = client.Collections.Use("Dog");

// Perform query
var response = await dogs.Query.NearMedia(
    query => query.Image(imageBytes).Build(),
    returnProperties: ["breed"],
    limit: 1
);

if (response.Objects.Any())
{
    Console.WriteLine(JsonSerializer.Serialize(response.Objects.First()));
}
```

See [Image search](https://docs.weaviate.io/weaviate/search/image) for more information.

## Search with an existing object

If you have an object ID, use the [`Near Object`](https://docs.weaviate.io/weaviate/api/graphql/search-operators#nearobject) operator to find similar objects to that object.

**Python**

```python
from weaviate.classes.query import MetadataQuery

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.query.near_object(
    near_object=uuid,  # A UUID of an object (e.g. "56b9449e-65db-5df4-887b-0a4773f52aa7")
    limit=2,
    return_metadata=MetadataQuery(distance=True)
)

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

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.query.nearObject('56b9449e-65db-5df4-887b-0a4773f52aa7', {
  limit: 2,
  returnMetadata: ['distance']
})

for (let object of result.objects) {
  console.log(JSON.stringify(object.properties, null, 2));
  console.log(JSON.stringify(object.metadata?.distance, null, 2));
}
```

**Go (v5)**

```go
response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
    graphql.Field{Name: "question"},
    graphql.Field{Name: "answer"},
    graphql.Field{
      Name: "_additional",
      Fields: []graphql.Field{
        {Name: "distance"},
      },
    },
  ).
  WithNearObject(client.GraphQL().NearObjectArgBuilder().
    WithID("56b9449e-65db-5df4-887b-0a4773f52aa7")).
  WithLimit(2).
  Do(ctx)
```

**Go (v6)**

```go
// A UUID of an object in the collection.
id := uuid.MustParse("5a6b7c8d-9e0f-4a1b-8c2d-1a2b3c4d5e6f")

jeopardy := client.Collections.Use("JeopardyQuestion")
response, err := jeopardy.Query.NearObject(ctx, query.NearObject{
  UUID:  id,
  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)
  if obj.Metadata.Distance != nil {
    fmt.Printf("distance: %v\n", *obj.Metadata.Distance)
  }
}
```

**Java**

```java
var response = jeopardy.query.nearObject(uuid, // A UUID of an object (e.g. "56b9449e-65db-5df4-887b-0a4773f52aa7")
    q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
  System.out.println(o.properties());
  System.out.println(o.queryMetadata().distance());
}
```

**C#**

```csharp
var response = await jeopardy.Query.NearObject(
    uuid, // A UUID of an object
    limit: 2,
    returnMetadata: MetadataOptions.Distance
);

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

**GraphQL**

```graphql
```

**Additional information**

To get the object ID, see [Retrieve the object ID](https://docs.weaviate.io/weaviate/search/basics#retrieve-the-object-id).

## Search with a vector

If you have an input vector, use the [`Near Vector`](https://docs.weaviate.io/weaviate/api/graphql/search-operators#nearvector) operator to find objects with similar vectors

**Python**

```python
from weaviate.classes.query import MetadataQuery

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.query.near_vector(
    near_vector=query_vector, # your query vector goes here
    limit=2,
    return_metadata=MetadataQuery(distance=True)
)

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

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.query.nearVector(queryVector, {
  limit: 2,
  returnMetadata: ['distance']
})

for (let object of result.objects) {
  console.log(JSON.stringify(object.properties, null, 2));
  console.log(JSON.stringify(object.metadata?.distance, null, 2));
}
```

**Go (v5)**

```go
// Edit the vector variable to add a vector of length 384
// vector := ADD_A_VECTOR_HERE

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
    graphql.Field{Name: "question"},
    graphql.Field{Name: "answer"},
    graphql.Field{
      Name: "_additional",
      Fields: []graphql.Field{
        {Name: "distance"},
      },
    },
  ).
  WithNearVector(client.GraphQL().NearVectorArgBuilder().
    WithVector(vector)).
  WithLimit(2).
  Do(ctx)
```

To run the example, paste the sample test vector into the code sample.

**Sample test vector**

vector := \[]float320.630052995

**Go (v6)**

```go
// A query vector, for example an embedding produced by your model.
vector := []float32{0.12, 0.20, 0.33}

jeopardy := client.Collections.Use("JeopardyQuestion")
response, err := jeopardy.Query.NearVector(ctx, query.NearVector{
  Target: &types.Vector{Single: 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)
  if obj.Metadata.Distance != nil {
    fmt.Printf("distance: %v\n", *obj.Metadata.Distance)
  }
}
```

**Java**

```java
var response = jeopardy.query.nearVector(queryVector, // your query vector goes here
    q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
  System.out.println(o.properties());
  System.out.println(o.queryMetadata().distance());
}
```

**C#**

```csharp
var response = await jeopardy.Query.NearVector(
    vectors: queryVector, // your query vector goes here
    limit: 2,
    returnMetadata: MetadataOptions.Distance
);

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

**GraphQL**

```graphql
{
  Get {
    JeopardyQuestion (
      limit: 2
      nearVector: {
        vector: [-0.0125526935, -0.021168863, -0.01076519, ...]
      }
    ) {
      question
      answer
      _additional {
        distance
      }
    }
  }
}
```

*This example's 1,536-number vector is shortened to its first 3 values. The HTML page has the full vector.*

## Named vectors

To search a collection that has [named vectors](https://docs.weaviate.io/weaviate/config-refs/collections#named-vectors), use the `target vector` field to specify which named vector to search.

**Python**

```python
from weaviate.classes.query import MetadataQuery

reviews = client.collections.use("WineReviewNV")
response = reviews.query.near_text(
    query="a sweet German white wine",
    limit=2,
    target_vector="title_country",  # Specify the target vector for named vector collections
    return_metadata=MetadataQuery(distance=True)
)

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

**JavaScript/TypeScript**

```ts
const myNVCollection = client.collections.use('WineReviewNV');

const result = await myNVCollection.query.nearText('a sweet German white wine', {
  targetVector: 'title_country',
  returnMetadata: ['distance'],
  limit: 2,
})

for (let object of result.objects) {
  console.log(JSON.stringify(object.properties, null, 2));
  console.log(JSON.stringify(object.metadata?.distance, null, 2));
}
```

**Go (v5)**

```go

className := "WineReviewNV"
targetVector := "title_country"
limit := 2

response, err := client.GraphQL().Get().
  WithClassName(className).
  WithFields(
    graphql.Field{Name: "_additional",
      Fields: []graphql.Field{{Name: "distance"}}},
  ).
  WithNearText((&graphql.NearTextArgumentBuilder{}).
    WithConcepts([]string{"a sweet German white wine"}).
    WithTargetVectors(targetVector),
  ).
  WithLimit(limit).
  Do(ctx)
```

**Go (v6)**

```go
reviews := client.Collections.Use("WineReviewNV")
response, err := reviews.Query.NearText(ctx, query.NearText{
  Concepts: []string{"a sweet German white wine"},
  // Select the named vector to search against.
  Target: query.VectorName("title_country"),
  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)
  fmt.Printf("distance: %v\n", *obj.Metadata.Distance)
}
```

**Java**

```java
CollectionHandle<Map<String, Object>> reviews =
    client.collections.use("WineReviewNV");
var response = reviews.query.nearText(
    Target.text("title_country", "a sweet German white wine"),
    q -> q.limit(2).returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
  System.out.println(o.properties());
  System.out.println(o.queryMetadata().distance());
}
```

**C#**

```csharp
var reviews = client.Collections.Use("WineReviewNV");
var response = await reviews.Query.NearText(
    query =>
        query(["a sweet German white wine"])
            .TargetVectorsMinimum("title_country"),
    limit: 2,
    returnMetadata: MetadataOptions.Distance
);

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

**GraphQL**

```graphql
{
  Get {
    WineReviewNV(
      limit: 2
      nearText: {
        targetVectors: ["title_country"]
        concepts: ["a sweet German white wine"]
      }
    ) {
      title
      review_body
      country
    }
  }
}
```

**Example response**

The output is like this:

```json
{
  "WineReviewNV": [
    {
      "country": "Austria",
      "review_body": "With notions of cherry and cinnamon on the nose and just slight fizz, this is a refreshing, fruit-driven sparkling ros\u00e9 that's full of strawberry and cherry notes\u2014it might just be the very definition of easy summer wine. It ends dry, yet refreshing.",
      "title": "Gebeshuber 2013 Frizzante Ros\u00e9 Pinot Noir (\u00d6sterreichischer Perlwein)"
    },
    {
      "country": "Austria",
      "review_body": "Beautifully perfumed, with acidity, white fruits and a mineral context. The wine is layered with citrus and lime, hints of fresh pineapple acidity. Screw cap.",
      "title": "Stadt Krems 2009 Steinterrassen Riesling (Kremstal)"
    }
  ]
}
```

## Set a similarity threshold

To set a similarity threshold between the search and target vectors, define a maximum `distance` (or `certainty`).

**Python**

```python
from weaviate.classes.query import MetadataQuery

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.query.near_text(
    query="animals in movies",
    distance=0.25, # max accepted distance
    return_metadata=MetadataQuery(distance=True)
)

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

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');
const maxDistance = 0.18;

const result = await jeopardy.query.nearText('animals in movies', {
  distance: maxDistance,
  returnMetadata: ['distance'],
})

result.objects.forEach(item => {
  console.log(JSON.stringify(item.properties, null, 2))
  console.log(item.metadata?.distance)
})
```

**Go (v5)**

```go
maxDistance := float32(0.18)
response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
    graphql.Field{Name: "question"},
    graphql.Field{Name: "answer"},
    graphql.Field{
      Name: "_additional",
      Fields: []graphql.Field{
        {Name: "distance"},
      },
    },
  ).
  WithNearText(client.GraphQL().NearTextArgBuilder().
    WithConcepts([]string{"animals in movies"}).
    WithDistance(maxDistance)).
  Do(ctx)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
response, err := jeopardy.Query.NearText(ctx, query.NearText{
  Concepts: []string{"animals in movies"},
  Similarity: query.Distance(0.25),
  ReturnMetadata: query.ReturnMetadata{
    Distance: true,
  },
})
if err != nil {
  // handle error
  panic(err)
}
for _, obj := range response.Objects {
  fmt.Printf("%v\n", obj.Properties)
  fmt.Printf("distance: %v\n", *obj.Metadata.Distance)
}
```

**Java**

```java
CollectionHandle<Map<String, Object>> jeopardy =
    client.collections.use("JeopardyQuestion");
var response = jeopardy.query.nearText("animals in movies", q -> q
    .distance(0.25f) // max accepted distance
    .returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
  System.out.println(o.properties());
  System.out.println(o.queryMetadata().distance());
}
```

**C#**

```csharp
var jeopardy = client.Collections.Use("JeopardyQuestion");
var response = await jeopardy.Query.NearText(
    "animals in movies",
    distance: 0.25f, // max accepted distance
    returnMetadata: MetadataOptions.Distance
);

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

**GraphQL**

```graphql
{
  Get {
    JeopardyQuestion(
      nearText: {
        concepts: ["animals in movies"]
        distance: 0.18
      }
    ) {
      question
      answer
      _additional {
        distance
      }
    }
  }
}
```

**Additional information**

- The distance value depends on many factors, including the vectorization model you use. Experiment with your data to find a value that works for you.
- [`certainty`](https://docs.weaviate.io/weaviate/config-refs/distances#distance-vs-certainty) is only available with `cosine` distance.
- To find the least similar objects, use the negative cosine distance with `nearVector` search.

## `limit` & `offset`

Use `limit` to set a fixed maximum number of objects to return.

Optionally, use `offset` to paginate the results.

`offset` + `limit` cannot exceed [`QUERY_MAXIMUM_RESULTS`](https://docs.weaviate.io/deploy/configuration/env-vars#QUERY_MAXIMUM_RESULTS) (default `10000`). A query past that ceiling returns an error rather than a truncated result set, and for a ranked search the ceiling is hard: narrow the query with filters, or raise `QUERY_MAXIMUM_RESULTS` (a higher value costs memory and query time). To iterate over every object without ranking, use a [cursor](https://docs.weaviate.io/weaviate/manage-objects/read-all-objects) instead, as cursors do not work with ranked searches.

**Python**

```python
from weaviate.classes.query import MetadataQuery

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.query.near_text(
    query="animals in movies",
    limit=2,  # return 2 objects
    offset=1,  # With an offset of 1
    return_metadata=MetadataQuery(distance=True)
)

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

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.query.nearText('animals in movies', {
  limit: 2,
  offset: 1,
  returnMetadata: ['distance']
})

console.log(JSON.stringify(result.objects, null, 2));
```

**Go (v5)**

```go
response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
    graphql.Field{Name: "question"},
    graphql.Field{Name: "answer"},
    graphql.Field{
      Name: "_additional",
      Fields: []graphql.Field{
        {Name: "distance"},
      },
    },
  ).
  WithNearText(client.GraphQL().NearTextArgBuilder().
    WithConcepts([]string{"animals in movies"})).
  WithLimit(2).
  WithOffset(1).
  Do(ctx)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
response, err := jeopardy.Query.NearText(ctx, query.NearText{
  Concepts: []string{"animals in movies"},
  Limit:  2,
  Offset: 1,
  ReturnMetadata: query.ReturnMetadata{
    Distance: true,
  },
})
if err != nil {
  // handle error
  panic(err)
}
for _, obj := range response.Objects {
  fmt.Printf("%v\n", obj.Properties)
  fmt.Printf("distance: %v\n", *obj.Metadata.Distance)
}
```

**Java**

```java
CollectionHandle<Map<String, Object>> jeopardy =
    client.collections.use("JeopardyQuestion");
var response = jeopardy.query.nearText("animals in movies", q -> q
    .limit(2) // return 2 objects
    .offset(1) // With an offset of 1
    .returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
  System.out.println(o.properties());
  System.out.println(o.queryMetadata().distance());
}
```

**C#**

```csharp
var jeopardy = client.Collections.Use("JeopardyQuestion");
var response = await jeopardy.Query.NearText(
    "animals in movies",
    limit: 2, // return 2 objects
    offset: 1, // With an offset of 1
    returnMetadata: MetadataOptions.Distance
);

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

**GraphQL**

```graphql
{
  Get {
    JeopardyQuestion(
      nearText: {
        concepts: ["animals in movies"]
      }
      limit: 2
      offset: 1
    ) {
      question
      answer
      _additional {
        distance
      }
    }
  }
}
```

## Limit result groups

To limit results to groups of similar distances to the query, use the [`autocut`](https://docs.weaviate.io/weaviate/api/graphql/additional-operators#autocut) filter to set the number of groups to return.

**Python**

```py
from weaviate.classes.query import MetadataQuery

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.query.near_text(
    query="animals in movies",
    auto_limit=1, # number of close groups
    return_metadata=MetadataQuery(distance=True)
)

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

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.query.nearText('animals in movies', {
  autoLimit: 1,
  returnMetadata: ['distance'],
})

result.objects.forEach(item => {
  console.log(JSON.stringify(item.properties, null, 2))
  console.log(item.metadata?.distance)
})
```

**Go (v5)**

```go
response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
    graphql.Field{Name: "question"},
    graphql.Field{Name: "answer"},
    graphql.Field{
      Name: "_additional",
      Fields: []graphql.Field{
        {Name: "distance"},
      },
    },
  ).
  WithNearText(client.GraphQL().NearTextArgBuilder().
    WithConcepts([]string{"animals in movies"})).
  WithAutocut(1).
  Do(ctx)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
response, err := jeopardy.Query.NearText(ctx, query.NearText{
  Concepts: []string{"animals in movies"},
  AutoLimit: 1, // number of close groups
  ReturnMetadata: query.ReturnMetadata{
    Distance: true,
  },
})
if err != nil {
  // handle error
  panic(err)
}
for _, obj := range response.Objects {
  fmt.Printf("%v\n", obj.Properties)
  fmt.Printf("distance: %v\n", *obj.Metadata.Distance)
}
```

**Java**

```java
CollectionHandle<Map<String, Object>> jeopardy =
    client.collections.use("JeopardyQuestion");
var response = jeopardy.query.nearText("animals in movies", q -> q
    .autolimit(1) // number of close groups
    .returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
  System.out.println(o.properties());
  System.out.println(o.queryMetadata().distance());
}
```

**C#**

```csharp
var jeopardy = client.Collections.Use("JeopardyQuestion");
var response = await jeopardy.Query.NearText(
    "animals in movies",
    autoLimit: 1, // number of close groups
    returnMetadata: MetadataOptions.Distance
);

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

**GraphQL**

```graphql
{
  Get {
    JeopardyQuestion(
      nearText: {
        concepts: ["animals in movies"]
      }
      autocut: 1
    ) {
      question
      answer
      _additional {
        distance
      }
    }
  }
}
```

**Example response**

The output is like this:

```json
{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "answer": "meerkats",
          "question": "Group of mammals seen <a href=\"http://www.j-archive.com/media/1998-06-01_J_28.jpg\" target=\"_blank\">here</a>:  [like Timon in <i>The Lion King</i>]",
          "_additional": { "distance": 0.17602634 }
        },
        {
          "answer": "dogs",
          "question": "Scooby-Doo, Goofy & Pluto are cartoon versions",
          "_additional": { "distance": 0.17842108 }
        }
      ]
    }
  }
}
```

## Group results

Use a property or a cross-reference to group results. To group returned objects, the query must include a `Near` search operator, such as `Near Text` or `Near Object`.

**Python**

```python
from weaviate.classes.query import MetadataQuery, GroupBy

jeopardy = client.collections.use("JeopardyQuestion")

group_by = GroupBy(
    prop="round",  # group by this property
    objects_per_group=2,  # maximum objects per group
    number_of_groups=2,  # maximum number of groups
)

response = jeopardy.query.near_text(
    query="animals in movies", # find object based on this query
    limit=10,  # maximum total objects
    return_metadata=MetadataQuery(distance=True),
    group_by=group_by
)


for o in response.objects:
    print(o.uuid)
    print(o.belongs_to_group)
    print(o.metadata.distance)

for grp, grp_items in response.groups.items():
    print("=" * 10 + grp_items.name + "=" * 10)
    print(grp_items.number_of_objects)
    for o in grp_items.objects:
        print(o.properties)
        print(o.metadata)
```

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.query.nearText('animals in movies', {
  limit: 10,
  returnMetadata: ['distance'],
  groupBy: {
    property: 'round',
    objectsPerGroup: 2,
    numberOfGroups: 2
  }
})

for (let group of result.objects) {
  console.log(group.uuid);
  console.log(JSON.stringify(group.belongsToGroup, null, 2));
  console.log(group.metadata?.distance);
}
```

**Go (v5)**

```go
maxGroups := 2
maxObjectsPerGroup := 2
response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithNearText(client.GraphQL().NearTextArgBuilder().
    WithConcepts([]string{"animals in movies"})).
  WithLimit(10).
  WithGroupBy(client.GraphQL().GroupByArgBuilder().
    WithPath([]string{"round"}).
    WithGroups(maxGroups).
    WithObjectsPerGroup(maxObjectsPerGroup)).
  WithFields(graphql.Field{
    Name: "_additional",
    Fields: []graphql.Field{
      {Name: "group",
        Fields: []graphql.Field{
          {Name: "id"},
          {Name: "groupedBy",
            Fields: []graphql.Field{
              {Name: "path"},
              {Name: "value"},
            },
          },
          {Name: "count"},
          {Name: "minDistance"},
          {Name: "maxDistance"},
          {Name: "hits",
            Fields: []graphql.Field{
              {Name: "question"},
              {Name: "answer"},
            },
          },
        },
      },
    },
  }).
  Do(ctx)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
response, err := jeopardy.Query.NearText.GroupBy(ctx,
  query.NearText{
    Concepts: []string{"animals in movies"},
    Limit:    10, // maximum total objects
    ReturnMetadata: query.ReturnMetadata{
      Distance: true,
    },
  },
  query.GroupBy{
    Property:       "round", // group by this property
    ObjectLimit:    2,       // maximum objects per group
    NumberOfGroups: 2,       // maximum number of groups
  },
)
if err != nil {
  // handle error
  panic(err)
}
for _, obj := range response.Objects {
  fmt.Printf("%v\n", obj.UUID)
  fmt.Printf("%v\n", obj.BelongsToGroup)
  fmt.Printf("distance: %v\n", *obj.Metadata.Distance)
}
for name, group := range response.Groups {
  fmt.Printf("========== %s ==========\n", name)
  fmt.Printf("%d\n", group.Size)
  for _, obj := range group.Objects {
    fmt.Printf("%v\n", obj.Properties)
  }
}
```

**Java**

```java
CollectionHandle<Map<String, Object>> jeopardy =
    client.collections.use("JeopardyQuestion");
var response = jeopardy.query.nearText("animals in movies", // find object based on this query
    q -> q.limit(10) // maximum total objects
        .returnMetadata(Metadata.DISTANCE),
    GroupBy.property("round", // group by this property
        2, // maximum number of groups
        2 // maximum objects per group
    ));
// response.objects().getFirst().vectors().getSingle("default");
for (var o : response.objects()) {
  // System.out.println(o.uuid());
  System.out.println(o.belongsToGroup());
  System.out.println(o.metadata().distance());
}

response.groups().forEach((groupName, group) -> {
  System.out
      .println("=" + "=".repeat(10) + group.name() + "=" + "=".repeat(10));
  System.out.println(group.numberOfObjects());
  for (var o : group.objects()) {
    System.out.println(o.properties());
    System.out.println(o.metadata());
  }
});
```

**C#**

```csharp
var jeopardy = client.Collections.Use("JeopardyQuestion");

var response = await jeopardy.Query.NearText(
    "animals in movies", // find object based on this query
    limit: 10, // maximum total objects
    returnMetadata: MetadataOptions.Distance,
    groupBy: new GroupByRequest("round") // group by this property
    {
        NumberOfGroups = 2, // maximum number of groups
        ObjectsPerGroup = 2, // maximum objects per group
    }
);

foreach (var o in response.Objects)
{
    Console.WriteLine(o.UUID);
    Console.WriteLine(o.BelongsToGroup);
    Console.WriteLine(o.Metadata.Distance);
}

foreach (var group in response.Groups.Values)
{
    Console.WriteLine($"=========={group.Name}==========");
    Console.WriteLine(group.Objects.Count());
    foreach (var o in group.Objects)
    {
        Console.WriteLine(JsonSerializer.Serialize(o.Properties));
        Console.WriteLine(JsonSerializer.Serialize(o.Metadata));
    }
}
```

**GraphQL**

```graphql
{
  Get {
    JeopardyQuestion(
      nearText: {
        concepts: ["animals in movies"],
      }
      limit: 10
      groupBy: {
        path: ["round"],
        groups: 2,
        objectsPerGroup: 2
      }
    ) {
      _additional {
        group {
          id
          groupedBy {
            path
            value
          }
          count
          minDistance
          maxDistance
          hits {
            question
            answer
          }
        }
      }
    }
  }
}
```

**Example response**

The output is like this:

```json
{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "_additional": {
            "group": {
              "count": 2,
              "groupedBy": {
                "path": [
                  "round"
                ],
                "value": "Jeopardy!"
              },
              "hits": [
                {
                  "answer": "meerkats",
                  "question": "Group of mammals seen <a href=\"http://www.j-archive.com/media/1998-06-01_J_28.jpg\" target=\"_blank\">here</a>:  [like Timon in <i>The Lion King</i>]"
                },
                {
                  "answer": "dogs",
                  "question": "Scooby-Doo, Goofy & Pluto are cartoon versions"
                }
              ],
              "id": 0,
              "maxDistance": 0.17842054,
              "minDistance": 0.17602539
            }
          }
        },
        {
          "_additional": {
            "group": {
              "count": 1,
              "groupedBy": {
                "path": [
                  "round"
                ],
                "value": "Double Jeopardy!"
              },
              "hits": [
                {
                  "answer": "fox",
                  "question": "In titles, animal associated with both Volpone and Reynard"
                }
              ],
              "id": 1,
              "maxDistance": 0.18770188,
              "minDistance": 0.18770188
            }
          }
        }
      ]
    }
  }
}
```

## Filter results

For more specific results, use a [`filter`](https://docs.weaviate.io/weaviate/api/graphql/filters) to narrow your search.

**Python**

```python
from weaviate.classes.query import MetadataQuery, Filter

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.query.near_text(
    query="animals in movies",
    filters=Filter.by_property("round").equal("Double Jeopardy!"),
    limit=2,
    return_metadata=MetadataQuery(distance=True),
)

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

**JavaScript/TypeScript**

```ts
const jeopardy = client.collections.use('JeopardyQuestion');

const result = await jeopardy.query.nearText('animals in movies', {
  limit: 2,
  returnMetadata: ['distance'],
  filters: jeopardy.filter.byProperty('round').equal('Double Jeopardy!')
})

result.objects.forEach(item => {
  console.log(JSON.stringify(item.properties, null, 2))
  console.log(item.metadata?.distance)
})
```

**Go (v5)**

```go
// Add "github.com/weaviate/weaviate-go-client/v5/weaviate/filters" to import

response, err := client.GraphQL().Get().
  WithClassName("JeopardyQuestion").
  WithFields(
    graphql.Field{Name: "question"},
    graphql.Field{Name: "answer"},
    graphql.Field{Name: "round"},
    graphql.Field{
      Name: "_additional",
      Fields: []graphql.Field{
        {Name: "distance"},
      },
    },
  ).
  WithNearText(client.GraphQL().NearTextArgBuilder().
    WithConcepts([]string{"animals in movies"})).
  WithLimit(2).
  WithWhere(filters.Where().
    WithPath([]string{"round"}).
    WithOperator(filters.Equal).
    WithValueString("Double Jeopardy!")).
  Do(ctx)
```

**Go (v6)**

```go
jeopardy := client.Collections.Use("JeopardyQuestion")
response, err := jeopardy.Query.NearText(ctx, query.NearText{
  Concepts: []string{"animals in movies"},
  Filter: &filter.Cond{
    Target:   "round",
    Operator: filter.Equal,
    Value:    "Double Jeopardy!",
  },
  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)
  fmt.Printf("distance: %v\n", *obj.Metadata.Distance)
}
```

**Java**

```java
CollectionHandle<Map<String, Object>> jeopardy =
    client.collections.use("JeopardyQuestion");
var response = jeopardy.query.nearText("animals in movies", q -> q
    .filters(Filter.property("round").eq("Double Jeopardy!"))
    .limit(2)
    .returnMetadata(Metadata.DISTANCE));

for (var o : response.objects()) {
  System.out.println(o.properties());
  System.out.println(o.queryMetadata().distance());
}
```

**C#**

```csharp
var jeopardy = client.Collections.Use("JeopardyQuestion");
var response = await jeopardy.Query.NearText(
    "animals in movies",
    filters: Filter.Property("round").IsEqual("Double Jeopardy!"),
    limit: 2,
    returnMetadata: MetadataOptions.Distance
);

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

**GraphQL**

```graphql
{
  Get {
    JeopardyQuestion(
      limit: 2
      nearText: {
        concepts: ["animals in movies"]
      }
      where: {
        path: ["round"]
        operator: Equal
        valueText: "Double Jeopardy!"
      }
    ) {
      question
      answer
      _additional {
        distance
      }
    }
  }
}
```

**Example response**

The output is like this:

```json
{
  "data": {
    "Get": {
      "JeopardyQuestion": [
        {
          "_additional": {
            "distance": 0.18759078
          },
          "answer": "fox",
          "question": "In titles, animal associated with both Volpone and Reynard",
          "round": "Double Jeopardy!"
        },
        {
          "_additional": {
            "distance": 0.19532347
          },
          "answer": "Swan",
          "question": "In a Tchaikovsky ballet, Prince Siegfried goes hunting for these animals & falls in love with 1 of them",
          "round": "Double Jeopardy!"
        }
      ]
    }
  }
}
```

## Diversity selection (MMR)

> [!NOTE]
>
> **Added in `v1.37.3` and `v1.38.6`**
>
> **Diversity selection (MMR)** for vector search was added in **`v1.37.3`**.\
> **Diversity selection (MMR)** for hybrid search was added in **`v1.38.6`**.

Standard vector search returns the closest matches to the query, which often means a cluster of near-duplicate results. **Maximal Marginal Relevance (MMR)** reranks results to balance relevance with diversity: each selected result must add something new to the result set.

Add the `diversity_selection` parameter to any vector search query:

```python
from weaviate.classes.query import Diversity

collection = client.collections.get("MMRDemo")

# Retrieve 20 candidates, then rerank to select 5 diverse results
response = collection.query.near_vector(
    near_vector=base_vec,
    limit=20,
    diversity_selection=Diversity.mmr(
        limit=5,
        balance=0.5,
    ),
)

for o in response.objects:
    print(o.properties["question"])
```

#### How it works

1. Weaviate runs a regular vector search to retrieve a candidate set (controlled by the query's `limit`)
2. The most relevant candidate is selected first
3. For each remaining candidate, MMR computes a score that balances query similarity against maximum similarity to already-selected results, weighted by `balance`
4. The candidate with the highest MMR score is selected next
5. Steps 3–4 repeat until the `Diversity.mmr(limit)` is reached

#### Parameters

| Parameter | Type | Description |
| - | - | - |
| `limit` | int | Number of results to return after MMR reranking. Must be at least `1` and no larger than the query's top-level `limit` (the candidate set size). Weaviate returns an error if it is omitted or out of range. |
| `balance` | float | Controls the relevance-diversity trade-off (0.0–1.0). `0.0` = pure diversity, `0.5` = balanced, `1.0` = pure relevance (equivalent to standard search). |

```python
from weaviate.classes.query import Diversity

collection = client.collections.get("MMRDemo")

# Pure diversity — maximize difference between results
response_diverse = collection.query.near_vector(
    near_vector=base_vec,
    limit=20,
    diversity_selection=Diversity.mmr(limit=5, balance=0.0),
)

# Balanced — equal weight on relevance and diversity
response_balanced = collection.query.near_vector(
    near_vector=base_vec,
    limit=20,
    diversity_selection=Diversity.mmr(limit=5, balance=0.5),
)

# Pure relevance — equivalent to standard vector search
response_relevant = collection.query.near_vector(
    near_vector=base_vec,
    limit=20,
    diversity_selection=Diversity.mmr(limit=5, balance=1.0),
)
```

Important notes:

- **Result ordering**: Results are ordered by MMR score, not query similarity. The first result is the most relevant, but subsequent results may have lower query similarity because they were chosen for diversity.
- **No reindexing needed**: MMR is applied at query time. You can use it on any existing collection without schema changes.
- **Supported queries**: `near_text`, `near_vector`, `near_object`, `near_image`, and `near_media`. Hybrid search is also supported, from `v1.38.6`. See [Diversity selection with hybrid search](https://docs.weaviate.io/weaviate/search/hybrid#diversity-selection-mmr).
- **Not supported**: multi-vector collections. Weaviate rejects these queries with an error instead of ignoring the diversity settings.

> [!TIP]
>
> A larger candidate set (higher top-level `limit`) gives MMR more results to choose from, improving diversity at the cost of slightly more computation. A good starting point is setting the candidate `limit` to 2–4x the MMR `limit`.

#### Pagination

Diversity selection changes what `offset` means. `offset` moves the candidate window rather than the page, so it must advance by the query's top-level `limit`, not by the page size or the number of objects returned. Weaviate does not validate the relationship between `offset` and `limit`, so a wrong `offset` produces no error and no warning. The only symptoms are objects that repeat across pages and objects that are never returned at all.

**Candidate window, worked example, and deep pages**

A diversified query works with two limits:

- the query's top-level `limit` is the **candidate window** that gets diversified, and
- the diversity `limit` is the **page size**, or how many objects come back.

Each page is taken from the slice `[offset, offset + limit)` of the relevance-ranked results, so `offset` must advance by the query `limit`:

```python
from weaviate.classes.query import Diversity

collection = client.collections.get("MMRDemo")

# The query limit is the size of the window that gets diversified.
# The diversity limit is the page size.
query_limit = 10
page_size = 3

# Advance offset by the query limit, NOT by the number of returned objects
for offset in range(0, 30, query_limit):
    page = collection.query.near_vector(
        near_vector=base_vec,
        limit=query_limit,
        offset=offset,
        diversity_selection=Diversity.mmr(limit=page_size, balance=0.5),
    )

    for o in page.objects:
        print(offset, o.properties["question"])
```

The usual pagination idiom, adding the number of returned objects to `offset`, is the failing case here. The page size is always smaller than or equal to the candidate window, so consecutive windows overlap. With a query `limit` of `10` and a diversity `limit` of `3`, advancing `offset` by `3` reads the windows `[0:10]`, `[3:13]`, and `[6:16]`, which is how objects come back twice while others are skipped.

When diversity selection is combined with a boost or with hybrid search, deep pages are also not stable slices of one fixed ranking. Both the boost pool and the two hybrid search legs fetch more candidates as `offset` grows, so which objects can reach a given page depends on how deep you have paged.

## Soft-rank with Boost

> [!NOTE]
>
> **Added in `v1.38`**

Vector search queries accept an optional `boost` argument that promotes or demotes matching documents without removing them. This is useful for biasing results by recency, popularity, a soft filter, or another property. Matching documents move up. Everything else stays in the results but ranks lower.

See [Boost](https://docs.weaviate.io/weaviate/search/boost) for the supported condition types (filter, property value, time decay, numeric decay), curve choices, blending semantics, and depth tuning.

## Related pages

- [Connect to Weaviate](https://docs.weaviate.io/weaviate/connections)
- For image search, see [Image search](https://docs.weaviate.io/weaviate/search/image).
- For search using the GraphQL API, see [GraphQL API](https://docs.weaviate.io/weaviate/api).
