How Rerank Works

The Rerank API endpoint, powered by the Rerank models, is a simple and very powerful tool for semantic search. Given a query and a list of documents, Rerank indexes the documents from most to least semantically relevant to the query.

Get Started

Example with Texts

In the example below, we use the Rerank API endpoint to index the list of docs from most to least relevant to the query What is the capital of the United States?.

Request

In this example, the documents being passed in are a list of strings:

import Cohere
co = cohere.Client(api_key="<YOUR API KEY>")

query = "What is the capital of the United States?"
docs = [
    "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.",
    "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
    "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
    "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.",
    "Capital punishment (the death penalty) has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment."]
results = co.rerank(model="rerank-english-v3.0", query=query, documents=docs, top_n=5, return_documents=True)

Response

{
	"id": "97813271-fe74-465d-b9d5-577e77079253",
	"results": [
		{
			"document": {
				"text": "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America."
			},
			"index": 3,
			"relevance_score": 0.9990564
		},
		{
			"document": {
				"text": "Capital punishment (the death penalty) has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment."
			},
			"index": 4,
			"relevance_score": 0.7516481
		},
		{
			"document": {
				"text": "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan."
			},
			"index": 1,
			"relevance_score": 0.08882029
		},
		{
			"document": {
				"text": "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274."
			},
			"index": 0,
			"relevance_score": 0.058238626
		},
		{
			"document": {
				"text": "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas."
			},
			"index": 2,
			"relevance_score": 0.019946935
		}
	],
	"meta": {
		"api_version": {
			"version": "2022-12-06"
		},
		"billed_units": {
			"search_units": 1
		}
	}
}

Example with Semi-structured Data:

Alternatively, you can pass in a JSON object and specify the fields you'd like to rank over. If you do not pass in any rank_fields, it will default to the text key.

Request

query = "What is the capital of the United States?"
docs = [
  {"Title":"Facts about Carson City","Content":"Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274."},
  {"Title":"The Commonwealth of Northern Mariana Islands","Content":"The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan."},
  {"Title":"The Capital of United States Virgin Islands","Content":"Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas."},
  {"Title":"Washington D.C.","Content":"Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America."},
	{"Title":"Capital Punishment in the US","Content":"Capital punishment (the death penalty) has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment."}]
results = co.rerank(model="rerank-english-v3.0", query=query, documents=docs, rank_fields=['Title','Content'],top_n=5, return_documents=True)

In the docs parameter, we are passing in a list of objects which have the key values: [Title ,Content]. As part of the Rerank call, we are specifying which keys to rank over, as well as the order in which the key value pairs should be considered.

{
	"id": "75a94aa7-6761-4a64-a2ae-4bc0a62bc601",
	"results": [
		{
			"document": {
				"Content": "Washington, D.C. (also known as simply Washington or D.C., and officially as the District of Columbia) is the capital of the United States. It is a federal district. The President of the USA and many major national government offices are in the territory. This makes it the political center of the United States of America.",
				"Title": "Washington D.C."
			},
			"index": 3,
			"relevance_score": 0.9987405
		},
		{
			"document": {
				"Content": "Capital punishment (the death penalty) has existed in the United States since before the United States was a country. As of 2017, capital punishment is legal in 30 of the 50 states. The federal government (including the United States military) also uses capital punishment.",
				"Title": "Capital Punishment in the US"
			},
			"index": 4,
			"relevance_score": 0.5011778
		},
		{
			"document": {
				"Content": "Charlotte Amalie is the capital and largest city of the United States Virgin Islands. It has about 20,000 people. The city is on the island of Saint Thomas.",
				"Title": "The Capital of United States Virgin Islands"
			},
			"index": 2,
			"relevance_score": 0.10070161
		},
		{
			"document": {
				"Content": "The Commonwealth of the Northern Mariana Islands is a group of islands in the Pacific Ocean that are a political division controlled by the United States. Its capital is Saipan.",
				"Title": "The Commonwealth of Northern Mariana Islands"
			},
			"index": 1,
			"relevance_score": 0.03197956
		},
		{
			"document": {
				"Content": "Carson City is the capital city of the American state of Nevada. At the 2010 United States Census, Carson City had a population of 55,274.",
				"Title": "Facts about Carson City"
			},
			"index": 0,
			"relevance_score": 0.019456575
		}
	],
	"meta": {
		"api_version": {
			"version": "2022-12-06"
		},
		"billed_units": {
			"search_units": 1
		}
	}
}

Multilingual Reranking

Cohere offers a multilingual model, rerank-multilingual-v3.0. Please note that performance may vary across languages. The model is trained on the following languages:

ISO CodeLanguage Name
afAfrikaans
amAmharic
arArabic
asAssamese
azAzerbaijani
beBelarusian
bgBulgarian
bnBengali
boTibetan
bsBosnian
caCatalan
cebCebuano
coCorsican
csCzech
cyWelsh
daDanish
deGerman
elGreek
enEnglish
eoEsperanto
esSpanish
etEstonian
euBasque
faPersian
fiFinnish
frFrench
fyFrisian
gaIrish
gdScots_gaelic
glGalician
guGujarati
haHausa
hawHawaiian
heHebrew
hiHindi
hmnHmong
hrCroatian
htHaitian_creole
huHungarian
hyArmenian
idIndonesian
igIgbo
isIcelandic
itItalian
jaJapanese
jvJavanese
kaGeorgian
kkKazakh
kmKhmer
knKannada
koKorean
kuKurdish
kyKyrgyz
LaLatin
LbLuxembourgish
LoLaothian
LtLithuanian
LvLatvian
mgMalagasy
miMaori
mkMacedonian
mlMalayalam
mnMongolian
mrMarathi
msMalay
mtMaltese
myBurmese
neNepali
nlDutch
noNorwegian
nyNyanja
orOriya
paPunjabi
plPolish
ptPortuguese
roRomanian
ruRussian
rwKinyarwanda
siSinhalese
skSlovak
slSlovenian
smSamoan
snShona
soSomali
sqAlbanian
srSerbian
stSesotho
suSundanese
svSwedish
swSwahili
taTamil
teTelugu
tgTajik
thThai
tkTurkmen
tlTagalog
trTurkish
ttTatar
ugUighur
ukUkrainian
urUrdu
uzUzbek
viVietnamese
woWolof
xhXhosa
yiYiddish
yoYoruba
zhChinese
zuZulu