Find and rerank documents (HTTP)

For details about additional languages, see:

Finds documents in a collection and reranks the results using a reranker model. This command supports two retrieval modes:

  • Hybrid search: Combines results from a vector search and a lexical search before reranking. For more information about hybrid search mechanics and best practices, see Find data with hybrid search.

  • Vector search with reranking: Reranks results from a vector search alone, without a lexical search.

To find documents using vector search, lexicographical matching, and filters without reranking, see Find documents (HTTP).

This method requires a collection with the following:

  • Vector enabled.

  • Rerank enabled. Alternatively, collections without rerank enabled can use the rerank override option. For an example, see Override the collection’s rerank provider.

  • Lexical enabled (only required for hybrid search).

For an example of creating a collection with vector, rerank, and lexical enabled, see Create a collection that supports hybrid search.

For hybrid search, documents must have both the $lexical and $vector fields populated. Documents missing either field are excluded from hybrid search. For vector search with reranking, only the $vector field is required.

Ready to write code? See the examples for this method to get started.

Data residency

When Hybrid Search (reranking) is enabled, query data is processed by a self-hosted reranking model hosted in the United States.

This may result in the transfer of content, including personal data, outside the region where your data is stored. Clients with data residency requirements restricting cross-border transfers should not use this feature.

Refer to the Data Processing Addendum (DPA) for additional details on processing locations and subprocessors.

Result

The response includes a data.documents property, which is an array of objects representing the documents returned by the reranker. The fields included in the returned documents depend on the subset of fields that were requested in the projection.

If requested, the response also includes a status.documentResponses property, which is a list of the scores from the retrieval process for each document.

If requested, the response also includes a status.sortVector property, which is the sort vector used for the underlying vector search.

This command always returns a single page of results, so data.nextPageState in the response is always null.

Example response without requesting sort vector or scores:

{
    "data": {
        "documents": [
            {
                "$lexical": "the house on the hill",
                "_id": "doc_a",
                "content": "the house on the hill",
                "tag": "x"
            },
            {
                "$lexical": "the tree in the woods",
                "_id": "doc_b",
                "content": "the tree in the woods",
                "tag": "x"
            }
        ],
        "nextPageState": null
    }
}

Example response with sort vector and scores requested:

{
    "data": {
        "documents": [
            {
                "$lexical": "the house on the hill",
                "_id": "doc_a",
                "content": "the house on the hill",
                "tag": "x"
            },
            {
                "$lexical": "the tree in the woods",
                "_id": "doc_b",
                "content": "the tree in the woods",
                "tag": "x"
            }
        ],
        "nextPageState": null
    },
    "status": {
        "documentResponses": [
            {
                "scores": {
                    "$rerank": -9.1015625,
                    "$vector": 0.96291006
                }
            },
            {
                "scores": {
                    "$rerank": -12.515625,
                    "$vector": 0.19139329
                }
            }
        ],
        "sortVector": [1.0, 1.0, 1.0]
    }
}

Example response if no documents were found, with sort vector and scores requested:

{
    "data": {
        "documents": [],
        "nextPageState": null
    },
    "status": {
        "documentResponses": [],
        "sortVector": [1.0, 1.0, 1.0]
    }
}

Signature

Use the findAndRerank command.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
    "findAndRerank": {
        "filter": FILTER,
        "options": {
            "hybridLimits": HYBRID_LIMITS,
            "includeScores": BOOLEAN,
            "includeSortVector": BOOLEAN,
            "limit": INTEGER,
            "rerankOn": STRING,
            "rerankQuery": STRING
        },
        "projection": PROJECTION,
        "sort": SORT
    }
}'

Parameters

Name Type Summary

filter

object

Optional. 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 (HTTP).

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

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.

Default: No filter, meaning any document is a possible match.

sort

object

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 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.

projection

object

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 (HTTP).

For more information, see Projections for collections (HTTP).

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.

options

object

Optional. The options for this operation. See Properties of options for more details.
Properties of options
Name Type Summary

limit

integer

Optional. Limit the total number of documents returned.

For an example, see Limit the number of documents returned.

Default: The limit set by the Data API.

hybridLimits

integer | object

Optional. Limit 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 dictionary in the form {"$vector": INTEGER, "$lexical": INTEGER}.

For an example, see Limit the number of documents returned by the underlying searches.

Default: The value of limit.

includeScores

boolean

Optional. Whether to include the scores from the reranking process in the response.

These scores are returned in the status.documentResponses property of the response as a list of objects. The list is index matched to the list of returned documents. Each score is an object such as {"$vector": 0.81, "$rerank": 0.12}.

For an example, see Include the scores in the response.

Default: False

includeSortVector

boolean

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.

The sort vector, if requested, is returned in the status.sortVector property of the response.

For an example, see Include the sort vector in the response.

Default: False

rerankOn

string

Required if you use $vector in sort; otherwise optional.

The document field to use for the reranking step. Once the underlying vector and lexical searches complete, the reranker compares the rerankQuery text with each document’s rerankOn 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 sort: "$lexical".

rerankQuery

string

Required if you use $vector in sort; otherwise optional.

Query text for the reranker step.

Once the underlying vector and lexical searches complete, the reranker compares the rerankQuery text with each document’s rerankOn field.

For an example, see Use a different query in the reranking step.

Default unless you use $vector in sort: the query used for the underlying vector search, which is specified by the sort parameter.

rerank

object

Optional. Overrides the reranking service configured for the collection, even if the collection does not have a reranking service configured.

The rerank object has the following properties:

  • provider (string): The name of the reranking provider. Only Nvidia is supported.

  • modelName (string): The name of a reranking model supported by the reranking provider. Only the NVIDIA llama-3.2-nv-rerankqa-1b-v2 reranking model reranker model is supported.

For an example, see Override the collection’s rerank provider.

Examples

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

Find documents with a hybrid search

With $vectorize

Use the sort parameter 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 can use a $vector query, as the "Without $vectorize" example demonstrates.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "sort": {
      "$hybrid": {
        "$lexical": "house hill grassy",
        "$vectorize": "A tree in the woods"
      }
    }
  }
}'
Without $vectorize

Use the sort parameter 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 an array of floats.

You must also specify the rerankQuery and rerankOn parameters.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "options": {
      "rerankOn": "$lexical",
      "rerankQuery": "house hill grassy"
    },
    "sort": {
      "$hybrid": {
        "$lexical": "house hill grassy",
        "$vector": [0.08, -0.62, 0.39]
      }
    }
  }
}'

Find documents with vector search and reranking

With $vectorize

Use the sort parameter to specify the query for the underlying vector search.

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

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "sort": {
      "$hybrid": {
        "$vectorize": "A tree in the woods"
      }
    }
  }
}'
Without $vectorize

Use the sort parameter to specify the query for the underlying vector search.

The $vector query is an array of floats.

You must also specify the rerankQuery and rerankOn parameters.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "options": {
      "rerankOn": "example_field",
      "rerankQuery": "A tree in the woods"
    },
    "sort": {
      "$hybrid": {
        "$vector": [0.08, -0.62, 0.39]
      }
    }
  }
}'

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.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "sort": {
      "$hybrid": "A tree in the woods"
    }
  }
}'

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 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 (HTTP).

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
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "filter": {
      "$and": [
        {"is_checked_out": false},
        {"number_of_pages": {"$lt": 300}}
      ]
    },
    "sort": {
      "$hybrid": "A tree in the woods"
    }
  }
}'
Without $vectorize
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "filter": {
      "$and": [
        {"is_checked_out": false},
        {"number_of_pages": {"$lt": 300}}
      ]
    },
    "options": {
      "rerankOn": "$lexical",
      "rerankQuery": "A tree in the woods"
    },
    "sort": {
      "$hybrid": {
        "$lexical": "house hill grassy",
        "$vector": [0.08, -0.62, 0.39]
      }
    }
  }
}'

Limit the number of documents returned

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

With $vectorize
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "options": {
      "limit": 2
    },
    "sort": {
      "$hybrid": "A tree in the woods"
    }
  }
}'
Without $vectorize
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "options": {
      "limit": 2,
      "rerankOn": "$lexical",
      "rerankQuery": "A tree in the woods"
    },
    "sort": {
      "$hybrid": {
        "$lexical": "house hill grassy",
        "$vector": [0.08, -0.62, 0.39]
      }
    }
  }
}'

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
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "options": {
      "hybridLimits": {
        "$lexical": 20,
        "$vector": 8
      }
    },
    "sort": {
      "$hybrid": "A tree in the woods"
    }
  }
}'
Without $vectorize
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "options": {
      "hybridLimits": {
        "$lexical": 20,
        "$vector": 8
      },
      "rerankOn": "$lexical",
      "rerankQuery": "A tree in the woods"
    },
    "sort": {
      "$hybrid": {
        "$lexical": "house hill grassy",
        "$vector": [0.08, -0.62, 0.39]
      }
    }
  }
}'

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.

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.

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
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "options": {},
    "projection": {
      "is_checked_out": true,
      "title": true
    },
    "sort": {
      "$hybrid": "A tree in the woods"
    }
  }
}'
Without $vectorize
curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "options": {
      "rerankOn": "$lexical",
      "rerankQuery": "A tree in the woods"
    },
    "projection": {
      "is_checked_out": true,
      "title": true
    },
    "sort": {
      "$hybrid": {
        "$lexical": "house hill grassy",
        "$vector": [0.08, -0.62, 0.39]
      }
    }
  }
}'

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.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "findAndRerank": {
    "sort": {
      "$hybrid": "A tree in the woods"
    },
    "options": {
      "rerank": {
        "provider": "nvidia",
        "modelName": "nvidia/llama-3.2-nv-rerankqa-1b-v2"
      }
    }
  }
}'

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM