Find and rerank documents (Go)

Hybrid search and reranking are currently in public preview. Development is ongoing, and the features and functionality are subject to change. Astra DB Serverless, and the use of such, is subject to the DataStax Preview Terms.

Finds documents in a collection through a retrieval process that uses a reranker model to combine results from a vector search and a lexical search. This process is called hybrid search. For more information about hybrid search mechanics and best practices, see Find data with hybrid search.

To find documents with vector search, lexicographical matching, and filters, see Find documents (Go).

This method requires the following:

A Serverless (vector) database in the AWS us-east-2 region.
A collection with vector, lexical, and rerank enabled. For more information, see Create a collection that supports hybrid search.

Collections without rerank can use the rerank override option. For an example, see Override the collection’s rerank provider.
Documents with the $lexical and $vector fields populated. Documents without both of these fields are excluded from hybrid search.

Ready to write code? See the examples for this method to get started. If you are new to the Data API, check out the quickstart.

Result

Returns a cursor (*cursors.FindAndRerankCursor) for iterating over documents returned by the reranker.

Iterating over the cursor yields cursors.RerankedResult structs, which represent the returned documents. The fields included in the returned documents depend on the subset of fields that were requested in the projection.

Each RerankedResult struct also includes a map of the scores from the retrieval process. If scores were not requested, the map is empty. Access the scores by calling GetScores() on the cursor, or by accessing the Scores field on the decoded cursor.

If requested, the result also includes the sort vector used for the underlying vector search. Calling GetSortVector() on the cursor reads the sort vector.

You must iterate over the cursor to fetch matching documents and their scores. If you need a list of all results, you can call All() on the cursor instead of iterating over the cursor. However, the time and memory required for this operation depend on the number of results.

Parameters

Use the FindAndRerank method, which belongs to the Collection type.

Method signature

func (c *Collection) FindAndRerank(
  f CollectionFilter,
  opts ...options.CollectionFindAndRerankOption
) cursors.FindAndRerankCursor

Name Type Summary

Name	Type	Summary
`f`	`CollectionFilter`	An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match the filter criteria. Filters can improve performance by reducing the number of documents that the Data API processes. You must use `&` to escape any `.` or `&` in field names in the filter clause. You cannot use `&` to escape any other characters. For more information, see Work with `.` and `&` in field names (Go). For a list of available filter operators and more examples, see Filter operators for collections (Go). Filters can use only indexed fields. If you apply selective indexing when you create a collection, you cannot reference non-indexed fields in a filter. For an example, see Use filters to restrict the search.
`opts`	`…options.CollectionFindAndRerankOption`	Optional. A builder to generate options for this operation. See Methods of the `CollectionFindAndRerankOption` builder for more details.

f

CollectionFilter

An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match the filter criteria. Filters can improve performance by reducing the number of documents that the Data API processes.

You must use & to escape any . or & in field names in the filter clause. You cannot use & to escape any other characters. For more information, see Work with . and & in field names (Go).

For a list of available filter operators and more examples, see Filter operators for collections (Go).

Filters can use only indexed fields. If you apply selective indexing when you create a collection, you cannot reference non-indexed fields in a filter.

For an example, see Use filters to restrict the search.

opts

…options.CollectionFindAndRerankOption

Optional. A builder to generate options for this operation. See Methods of the CollectionFindAndRerankOption builder for more details.

Methods of the `CollectionFindAndRerankOption` builder
Method	Summary
`SetSort(v sort.Sortable)`	Specifies queries for the underlying vector and lexical searches. The `$lexical` query is a string of space-separated keywords or terms. The `$vector` query is an array of floats or a `DataAPIVector` object that serves as a search vector. If you use this query, you must specify the `rerankQuery` and `rerankOn` parameters. The `$vectorize` query is a string that the configured embedding provider will convert into a search vector. Only collections that have vectorize enabled can use `$vectorize`. `$vector` and `$vectorize` can’t be used together. You can also use shorthand to specify a single search string for both the `$vectorize` and `$lexical` queries. For examples, see Find documents with a hybrid search and Use shorthand to specify a single search string.
`SetProjection(v map[string]any)`	Optional. Controls which fields are included or excluded in the returned document. You must use `&` to escape any `.` or `&` in field names in the projection clause. You cannot use `&` to escape any other characters. For more information, see Work with `.` and `&` in field names (Go). For more information, see Projections for collections (Go). Default: The default projection for the collection. All fields prefixed with `$` are excluded by default and will only be returned if you include them in the projection. `_id` is included by default and will always be returned unless you exclude it from the projection. For an example, see Include only specific fields in the response.
`SetLimit(v int)`	Optional. Limits the total number of documents returned. Once the limit is reached, or the cursor is exhausted due to lack of matching documents, nothing more is returned. For an example, see Limit the number of documents returned. Default: The limit set by the Data API.
`SetHybridLimits(v any)`	Optional. Limits the number of documents returned by the underlying vector and lexical searches. If a single number is specified, it applies to both the vector and lexical searches. To set different limits for the vector and lexical searches, specify a map in the form `map[string]int{"$vector": INTEGER, "$lexical": INTEGER}`. For an example, see Limit the number of documents returned by the underlying searches. Default: The value of `SetLimit()`.
`SetIncludeScores(v bool)`	Optional. Whether to include the scores from the reranking process in the response. Access the scores by calling `GetScores()` on the returned cursor, or by accessing the `Scores` field on the decoded cursor. If false, the `Scores` attribute of each `RerankedResult` struct is an empty map. For an example, see Include the scores in the response. Default: False
`SetIncludeSortVector(v bool)`	Optional. Whether to include the sort vector that was used for the underlying vector search in the response. This can be useful if you query through the `$vectorize` field instead of the `$vector` field, since you don’t know the sort vector in advance. Calling `GetSortVector()` on the returned cursor reads the sort vector. For an example, see Include the sort vector in the response. Default: False
`SetRerankOn(v string)`	Required if you use `$vector` in `SetSort()`; otherwise optional. The document field to use for the reranking step. Once the underlying vector and lexical searches complete, the reranker compares the "rerank query" text with each document’s "rerank on" field. The reserved `$lexical` field is often used for this parameter, but you can specify any field that stores a string. Documents without this field or with a null or non-string value are excluded. Default unless you use `$vector` in `SetSort()`: `"$lexical"`.
`SetRerankQuery(v string)`	Required if you use `$vector` in `SetSort()`; otherwise optional. The query text for the reranker step. Once the underlying vector and lexical searches complete, the reranker compares the "rerank query" text with each document’s "rerank on" field. For an example, see Use a different query in the reranking step. Default unless you use `$vector` in `SetSort()`: the query used for the underlying vector search, which is specified by the `SetSort()` method.
`UpdateRerank(v …options.RerankServiceOption)`	Optional. Overrides the reranking service configured for the collection, even if the collection does not have a reranking service configured. Only the NVIDIA llama-3.2-nv-rerankqa-1b-v2 reranking model reranker model is supported. Only collections in databases in the AWS `us-east-2` region support this parameter. For an example, see Override the collection’s rerank provider.
`UpdateAPIOptions(v …APIOption)`	Optional. General API options for this operation, including the timeout.

Examples

The following examples demonstrate how to find documents with hybrid search.

Find documents with a hybrid search

With $vectorize
Without $vectorize

Use the SetSort() method to specify the queries for the underlying vector search and lexical search.

The $lexical query is a string of space-separated keywords or terms.

The $vectorize query is a string that the configured embedding provider will convert into a search vector. Alternatively, you use a $vector query, as the "Without $vectorize" example demonstrates.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	vectorizeQuery := "A tree in the woods"
	lexicalQuery := "house hill grassy"

	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.HybridBy(sort.HybridSort{
				Vectorize: &vectorizeQuery,
				Lexical:   &lexicalQuery,
			})),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

Use the SetSort() method to specify the queries for the underlying vector search and lexical search.

The $lexical query is a string of space-separated keywords or terms.

The $vector query is a DataAPIVector object or an array of floats.

You must also specify the rerankQuery and rerankOn parameters.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	vectorQuery := []float32{0.08, -0.62, 0.39}
	lexicalQuery := "house hill grassy"

	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.HybridBy(sort.HybridSort{
				Vector:  &vectorQuery,
				Lexical: &lexicalQuery,
			})).
			SetRerankQuery("A tree in the woods").
			SetRerankOn("$lexical"),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

Use shorthand to specify a single search string

If your collection has vectorize enabled, you can use shorthand to specify the same string for both the $vectorize and $lexical queries.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.Hybrid("A tree in the woods")),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

Use a different query in the reranking step

The results of the underlying vector search and lexical search are run through a reranker model. The reranker uses a search string to rerank the documents that were returned by the underlying searches.

If you query through the $vector field, you must specify the search string for the reranker to use and the field to rerank the documents on.

If you query through the $vectorize field, the reranker will use the string that was used to perform the underlying vector search unless you specify a different string. It will also rerank documents on their $lexical field, unless you specify a different field.

Use the SetRerankQuery() method to specify the search string for the reranker. Use the SetRerankOn() method to specify which field to rerank the documents by.

With $vectorize
Without $vectorize

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.Hybrid("A tree in the woods")).
			SetRerankQuery("A house on a hill"),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	vectorQuery := []float32{0.08, -0.62, 0.39}
	lexicalQuery := "house hill grassy"

	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.HybridBy(sort.HybridSort{
				Vector:  &vectorQuery,
				Lexical: &lexicalQuery,
			})).
			SetRerankQuery("A tree in the woods").
			SetRerankOn("$lexical"),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

Use filters to restrict the search

You can use a filter to find documents that match specific criteria. For example, you can find documents with an is_checked_out value of false and a number_of_pages value less than 300.

Only documents that match the filter will be included in the hybrid search.

For a list of available filter operators and more examples, see Filter operators for collections (Go).

Filters can use only indexed fields. If you apply selective indexing when you create a collection, you cannot reference non-indexed fields in a filter.

With $vectorize
Without $vectorize

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	cursor := collection.FindAndRerank(
		filter.And(
			filter.Eq("is_checked_out", false),
			filter.Lt("number_of_pages", 300),
		),
		options.CollectionFindAndRerank().
			SetSort(sort.Hybrid("A tree in the woods")),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	vectorQuery := []float32{0.08, -0.62, 0.39}
	lexicalQuery := "house hill grassy"

	cursor := collection.FindAndRerank(
		filter.And(
			filter.Eq("is_checked_out", false),
			filter.Lt("number_of_pages", 300),
		),
		options.CollectionFindAndRerank().
			SetSort(sort.HybridBy(sort.HybridSort{
				Vector:  &vectorQuery,
				Lexical: &lexicalQuery,
			})).
			SetRerankQuery("A tree in the woods").
			SetRerankOn("$lexical"),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

Limit the number of documents returned

Specify a limit to only fetch up to a certain number of documents.

With $vectorize
Without $vectorize

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.Hybrid("A tree in the woods")).
			SetLimit(2),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	vectorQuery := []float32{0.08, -0.62, 0.39}
	lexicalQuery := "house hill grassy"

	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.HybridBy(sort.HybridSort{
				Vector:  &vectorQuery,
				Lexical: &lexicalQuery,
			})).
			SetRerankQuery("A tree in the woods").
			SetRerankOn("$lexical").
			SetLimit(2),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

Limit the number of documents returned by the underlying searches

You can customize the number of documents returned by the underlying vector and lexical searches.

You can provide a single number, which is then used for both the vector search and the lexical search. Or, you can specify a different limit for each search. Specifying different limits can help boost the importance of one type of search over the other.

By default, each underlying search uses the same limit as the overall method.

With $vectorize
Without $vectorize

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.Hybrid("A tree in the woods")).
			SetHybridLimits(map[string]int{"$vector": 8, "$lexical": 20}),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	vectorQuery := []float32{0.08, -0.62, 0.39}
	lexicalQuery := "house hill grassy"

	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.HybridBy(sort.HybridSort{
				Vector:  &vectorQuery,
				Lexical: &lexicalQuery,
			})).
			SetRerankQuery("A tree in the woods").
			SetRerankOn("$lexical").
			SetHybridLimits(map[string]int{"$vector": 8, "$lexical": 20}),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

Include the scores in the response

You can request the scores to be returned alongside the documents.

The reranking retrieval process assigns scores to each document, such as vector similarity and reranker scores, and then compares those scores across all retrieved documents to determine the best overall results.

For general information, see Find data with vector search and Find data with hybrid search.

Each RerankedResult struct yielded by the returned cursor contains a Scores field. This attribute is a map associating score names to their score. For example: map[string]float32{"$vector": 0.81, "$rerank": 0.12}.

Access the scores by calling GetScores() on the cursor, or by accessing the Scores field on the decoded cursor.

With $vectorize
Without $vectorize

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.Hybrid("A tree in the woods")).
			SetIncludeScores(true),
	)

	// Iterate over the scores for the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Scores)
	}
}

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	vectorQuery := []float32{0.08, -0.62, 0.39}
	lexicalQuery := "house hill grassy"

	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.HybridBy(sort.HybridSort{
				Vector:  &vectorQuery,
				Lexical: &lexicalQuery,
			})).
			SetRerankQuery("A tree in the woods").
			SetRerankOn("$lexical").
			SetIncludeScores(true),
	)

	// Iterate over the scores for the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Scores)
	}
}

Include the sort vector in the response

You can include the sort vector in the result. This can be useful if you use $vectorize and a search string in the sort parameter, since you don’t know the sort vector in advance.

Calling GetSortVector() on the returned cursor reads the sort vector.

With $vectorize
Without $vectorize

package main

import (
	"context"
	"fmt"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.Hybrid("A tree in the woods")).
			SetIncludeSortVector(true),
	)

	// Inspect the sort vector
	vector := cursor.GetSortVector(ctx)
	fmt.Println(vector)
}

package main

import (
	"context"
	"fmt"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	vectorQuery := []float32{0.08, -0.62, 0.39}
	lexicalQuery := "house hill grassy"

	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.HybridBy(sort.HybridSort{
				Vector:  &vectorQuery,
				Lexical: &lexicalQuery,
			})).
			SetRerankQuery("A tree in the woods").
			SetRerankOn("$lexical").
			SetIncludeSortVector(true),
	)

	// Inspect the sort vector
	vector := cursor.GetSortVector(ctx)
	fmt.Println(vector)
}

Include only specific fields in the response

To specify which fields to include or exclude in the returned documents, use a projection.

All fields prefixed with $ are excluded by default and will only be returned if you include them in the projection. _id is included by default and will always be returned unless you exclude it from the projection.

With $vectorize
Without $vectorize

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.Hybrid("A tree in the woods")).
			SetProjection(map[string]any{
				"is_checked_out": true,
				"title":          true,
			}),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	vectorQuery := []float32{0.08, -0.62, 0.39}
	lexicalQuery := "house hill grassy"

	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.HybridBy(sort.HybridSort{
				Vector:  &vectorQuery,
				Lexical: &lexicalQuery,
			})).
			SetProjection(map[string]any{
				"is_checked_out": true,
				"title":          true,
			}).
			SetRerankQuery("A tree in the woods").
			SetRerankOn("$lexical"),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

Override the collection’s rerank provider

You can override the reranking service configured for the collection, even if the collection does not have a reranking service configured.

Only the NVIDIA llama-3.2-nv-rerankqa-1b-v2 reranking model reranker model is supported.

Only collections in databases in the AWS us-east-2 region support this parameter.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/datastax/astra-db-go/v2/astra"
	"github.com/datastax/astra-db-go/v2/astra/cursors"
	"github.com/datastax/astra-db-go/v2/astra/filter"
	"github.com/datastax/astra-db-go/v2/astra/options"
	"github.com/datastax/astra-db-go/v2/astra/sort"
)

func main() {
	ctx := context.Background()

	// Get an existing collection
	client := astra.NewClient()

	database := client.Database(
		"API_ENDPOINT",
		options.API().SetToken("APPLICATION_TOKEN"),
	)

	collection := database.Collection("COLLECTION_NAME")

	// Find documents
	cursor := collection.FindAndRerank(
		filter.F{},
		options.CollectionFindAndRerank().
			SetSort(sort.Hybrid("A tree in the woods")).
			UpdateRerank(options.RerankService().
				SetProvider("nvidia").
				SetModelName("nvidia/llama-3.2-nv-rerankqa-1b-v2")),
	)

	// Iterate over the found documents
	for cursor.Next(ctx) {
		var result cursors.RerankedResult[astra.Document]
		if err := cursor.Decode(&result); err != nil {
			log.Fatal(err)
		}
		fmt.Println(result.Document.ToMap())
	}
}

Client reference

For more information, see the client reference.

Find and rerank documents (Go)

Result

Parameters

Examples

Find documents with a hybrid search

Use shorthand to specify a single search string

Use a different query in the reranking step

Use filters to restrict the search

Limit the number of documents returned

Limit the number of documents returned by the underlying searches

Include the scores in the response

Include the sort vector in the response

Include only specific fields in the response

Override the collection’s rerank provider

Client reference

Was this helpful?

Give Feedback