Skip to content
LlamaIndex OSS Documentation
API Reference

Retrievers

Create Retriever
retrievers.create(RetrieverCreateParams**kwargs) -> Retriever
POST/api/v1/retrievers
Upsert Retriever
retrievers.upsert(RetrieverUpsertParams**kwargs) -> Retriever
PUT/api/v1/retrievers
List Retrievers
retrievers.list(RetrieverListParams**kwargs) -> RetrieverListResponse
GET/api/v1/retrievers
Get Retriever
retrievers.get(strretriever_id, RetrieverGetParams**kwargs) -> Retriever
GET/api/v1/retrievers/{retriever_id}
Update Retriever
retrievers.update(strretriever_id, RetrieverUpdateParams**kwargs) -> Retriever
PUT/api/v1/retrievers/{retriever_id}
Delete Retriever
retrievers.delete(strretriever_id, RetrieverDeleteParams**kwargs)
DELETE/api/v1/retrievers/{retriever_id}
Direct Retrieve
retrievers.search(RetrieverSearchParams**kwargs) -> CompositeRetrievalResult
POST/api/v1/retrievers/retrieve
ModelsExpand Collapse
Literal["routing", "full"]

Enum for the mode of composite retrieval.

One of the following:
"routing"
"full"
class CompositeRetrievalResult: …
Deprecatedimage_nodes: Optional[List[PageScreenshotNodeWithScore]]

The image nodes retrieved by the pipeline for the given query. Deprecated - will soon be replaced with ‘page_screenshot_nodes’.

node: Node
file_id: str

The ID of the file that the page screenshot was taken from

formatuuid
image_size: int

The size of the image in bytes

minimum0
page_index: int

The index of the page for which the screenshot is taken (0-indexed)

minimum0
metadata: Optional[Dict[str, object]]

Metadata for the screenshot

score: float

The score of the screenshot node

class_name: Optional[str]
nodes: Optional[List[Node]]

The retrieved nodes from the composite retrieval.

node: NodeNode
id: str

The ID of the retrieved node.

formatuuid
end_char_idx: Optional[int]

The end character index of the retrieved node in the document

pipeline_id: str

The ID of the pipeline this node was retrieved from.

formatuuid
retriever_id: str

The ID of the retriever this node was retrieved from.

formatuuid
retriever_pipeline_name: str

The name of the retrieval pipeline this node was retrieved from.

start_char_idx: Optional[int]

The start character index of the retrieved node in the document

text: str

The text of the retrieved node.

metadata: Optional[Dict[str, object]]

Metadata associated with the retrieved node.

class_name: Optional[str]
score: Optional[float]
page_figure_nodes: Optional[List[PageFigureNodeWithScore]]

The page figure nodes retrieved by the pipeline for the given query.

node: Node
confidence: float

The confidence of the figure

maximum1
minimum0
figure_name: str

The name of the figure

figure_size: int

The size of the figure in bytes

minimum0
file_id: str

The ID of the file that the figure was taken from

formatuuid
page_index: int

The index of the page for which the figure is taken (0-indexed)

minimum0
is_likely_noise: Optional[bool]

Whether the figure is likely to be noise

metadata: Optional[Dict[str, object]]

Metadata for the figure

score: float

The score of the figure node

class_name: Optional[str]
class ReRankConfig: …
top_n: Optional[int]

The number of nodes to retrieve after reranking over retrieved nodes from all retrieval tools.

minimum1
type: Optional[Literal["system_default", "llm", "cohere", 3 more]]

The type of reranker to use.

One of the following:
"system_default"
"llm"
"cohere"
"bedrock"
"score"
"disabled"
class Retriever: …

An entity that retrieves context nodes from several sub RetrieverTools.

id: str

Unique identifier

formatuuid
name: str

A name for the retriever tool. Will default to the pipeline name if not provided.

maxLength3000
minLength1
project_id: str

The ID of the project this retriever resides in.

formatuuid
created_at: Optional[datetime]

Creation datetime

formatdate-time
pipelines: Optional[List[RetrieverPipeline]]

The pipelines this retriever uses.

description: Optional[str]

A description of the retriever tool.

maxLength15000
name: Optional[str]

A name for the retriever tool. Will default to the pipeline name if not provided.

maxLength3000
minLength1
pipeline_id: str

The ID of the pipeline this tool uses.

formatuuid
preset_retrieval_parameters: Optional[PresetRetrievalParams]

Parameters for retrieval configuration.

alpha: Optional[float]

Alpha value for hybrid retrieval to determine the weights between dense and sparse retrieval. 0 is sparse retrieval and 1 is dense retrieval.

maximum1
minimum0
class_name: Optional[str]
dense_similarity_cutoff: Optional[float]

Minimum similarity score wrt query for retrieval

maximum1
minimum0
dense_similarity_top_k: Optional[int]

Number of nodes for dense retrieval.

maximum100
minimum1
enable_reranking: Optional[bool]

Enable reranking for retrieval

files_top_k: Optional[int]

Number of files to retrieve (only for retrieval mode files_via_metadata and files_via_content).

maximum5
minimum1
rerank_top_n: Optional[int]

Number of reranked nodes for returning.

maximum100
minimum1
retrieval_mode: Optional[RetrievalMode]

The retrieval mode for the query.

One of the following:
"chunks"
"files_via_metadata"
"files_via_content"
"auto_routed"
Deprecatedretrieve_image_nodes: Optional[bool]

Whether to retrieve image nodes.

retrieve_page_figure_nodes: Optional[bool]

Whether to retrieve page figure nodes.

retrieve_page_screenshot_nodes: Optional[bool]

Whether to retrieve page screenshot nodes.

search_filters: Optional[MetadataFilters]

Metadata filters for vector stores.

filters: List[Filter]
One of the following:
class FilterMetadataFilter: …

Comprehensive metadata filter for vector stores to support more operators.

Value uses Strict types, as int, float and str are compatible types and were all converted to string before.

See: https://docs.pydantic.dev/latest/usage/types/#strict-types

key: str
value: Union[float, str, List[str], 3 more]
One of the following:
float
str
List[str]
List[float]
List[int]
operator: Optional[Literal["==", ">", "<", 11 more]]

Vector store filter operator.

One of the following:
"=="
">"
"<"
"!="
">="
"<="
"in"
"nin"
"any"
"all"
"text_match"
"text_match_insensitive"
"contains"
"is_empty"
condition: Optional[Literal["and", "or", "not"]]

Vector store filter conditions to combine different filters.

One of the following:
"and"
"or"
"not"
search_filters_inference_schema: Optional[Dict[str, Union[Dict[str, object], List[object], str, 3 more]]]

JSON Schema that will be used to infer search_filters. Omit or leave as null to skip inference.

One of the following:
Dict[str, object]
List[object]
str
float
bool
sparse_similarity_top_k: Optional[int]

Number of nodes for sparse retrieval.

maximum100
minimum1
updated_at: Optional[datetime]

Update datetime

formatdate-time
class RetrieverCreate: …
name: str

A name for the retriever tool. Will default to the pipeline name if not provided.

maxLength3000
minLength1
pipelines: Optional[List[RetrieverPipeline]]

The pipelines this retriever uses.

description: Optional[str]

A description of the retriever tool.

maxLength15000
name: Optional[str]

A name for the retriever tool. Will default to the pipeline name if not provided.

maxLength3000
minLength1
pipeline_id: str

The ID of the pipeline this tool uses.

formatuuid
preset_retrieval_parameters: Optional[PresetRetrievalParams]

Parameters for retrieval configuration.

alpha: Optional[float]

Alpha value for hybrid retrieval to determine the weights between dense and sparse retrieval. 0 is sparse retrieval and 1 is dense retrieval.

maximum1
minimum0
class_name: Optional[str]
dense_similarity_cutoff: Optional[float]

Minimum similarity score wrt query for retrieval

maximum1
minimum0
dense_similarity_top_k: Optional[int]

Number of nodes for dense retrieval.

maximum100
minimum1
enable_reranking: Optional[bool]

Enable reranking for retrieval

files_top_k: Optional[int]

Number of files to retrieve (only for retrieval mode files_via_metadata and files_via_content).

maximum5
minimum1
rerank_top_n: Optional[int]

Number of reranked nodes for returning.

maximum100
minimum1
retrieval_mode: Optional[RetrievalMode]

The retrieval mode for the query.

One of the following:
"chunks"
"files_via_metadata"
"files_via_content"
"auto_routed"
Deprecatedretrieve_image_nodes: Optional[bool]

Whether to retrieve image nodes.

retrieve_page_figure_nodes: Optional[bool]

Whether to retrieve page figure nodes.

retrieve_page_screenshot_nodes: Optional[bool]

Whether to retrieve page screenshot nodes.

search_filters: Optional[MetadataFilters]

Metadata filters for vector stores.

filters: List[Filter]
One of the following:
class FilterMetadataFilter: …

Comprehensive metadata filter for vector stores to support more operators.

Value uses Strict types, as int, float and str are compatible types and were all converted to string before.

See: https://docs.pydantic.dev/latest/usage/types/#strict-types

key: str
value: Union[float, str, List[str], 3 more]
One of the following:
float
str
List[str]
List[float]
List[int]
operator: Optional[Literal["==", ">", "<", 11 more]]

Vector store filter operator.

One of the following:
"=="
">"
"<"
"!="
">="
"<="
"in"
"nin"
"any"
"all"
"text_match"
"text_match_insensitive"
"contains"
"is_empty"
condition: Optional[Literal["and", "or", "not"]]

Vector store filter conditions to combine different filters.

One of the following:
"and"
"or"
"not"
search_filters_inference_schema: Optional[Dict[str, Union[Dict[str, object], List[object], str, 3 more]]]

JSON Schema that will be used to infer search_filters. Omit or leave as null to skip inference.

One of the following:
Dict[str, object]
List[object]
str
float
bool
sparse_similarity_top_k: Optional[int]

Number of nodes for sparse retrieval.

maximum100
minimum1
class RetrieverPipeline: …
description: Optional[str]

A description of the retriever tool.

maxLength15000
name: Optional[str]

A name for the retriever tool. Will default to the pipeline name if not provided.

maxLength3000
minLength1
pipeline_id: str

The ID of the pipeline this tool uses.

formatuuid
preset_retrieval_parameters: Optional[PresetRetrievalParams]

Parameters for retrieval configuration.

alpha: Optional[float]

Alpha value for hybrid retrieval to determine the weights between dense and sparse retrieval. 0 is sparse retrieval and 1 is dense retrieval.

maximum1
minimum0
class_name: Optional[str]
dense_similarity_cutoff: Optional[float]

Minimum similarity score wrt query for retrieval

maximum1
minimum0
dense_similarity_top_k: Optional[int]

Number of nodes for dense retrieval.

maximum100
minimum1
enable_reranking: Optional[bool]

Enable reranking for retrieval

files_top_k: Optional[int]

Number of files to retrieve (only for retrieval mode files_via_metadata and files_via_content).

maximum5
minimum1
rerank_top_n: Optional[int]

Number of reranked nodes for returning.

maximum100
minimum1
retrieval_mode: Optional[RetrievalMode]

The retrieval mode for the query.

One of the following:
"chunks"
"files_via_metadata"
"files_via_content"
"auto_routed"
Deprecatedretrieve_image_nodes: Optional[bool]

Whether to retrieve image nodes.

retrieve_page_figure_nodes: Optional[bool]

Whether to retrieve page figure nodes.

retrieve_page_screenshot_nodes: Optional[bool]

Whether to retrieve page screenshot nodes.

search_filters: Optional[MetadataFilters]

Metadata filters for vector stores.

filters: List[Filter]
One of the following:
class FilterMetadataFilter: …

Comprehensive metadata filter for vector stores to support more operators.

Value uses Strict types, as int, float and str are compatible types and were all converted to string before.

See: https://docs.pydantic.dev/latest/usage/types/#strict-types

key: str
value: Union[float, str, List[str], 3 more]
One of the following:
float
str
List[str]
List[float]
List[int]
operator: Optional[Literal["==", ">", "<", 11 more]]

Vector store filter operator.

One of the following:
"=="
">"
"<"
"!="
">="
"<="
"in"
"nin"
"any"
"all"
"text_match"
"text_match_insensitive"
"contains"
"is_empty"
condition: Optional[Literal["and", "or", "not"]]

Vector store filter conditions to combine different filters.

One of the following:
"and"
"or"
"not"
search_filters_inference_schema: Optional[Dict[str, Union[Dict[str, object], List[object], str, 3 more]]]

JSON Schema that will be used to infer search_filters. Omit or leave as null to skip inference.

One of the following:
Dict[str, object]
List[object]
str
float
bool
sparse_similarity_top_k: Optional[int]

Number of nodes for sparse retrieval.

maximum100
minimum1
List[Retriever]
id: str

Unique identifier

formatuuid
name: str

A name for the retriever tool. Will default to the pipeline name if not provided.

maxLength3000
minLength1
project_id: str

The ID of the project this retriever resides in.

formatuuid
created_at: Optional[datetime]

Creation datetime

formatdate-time
pipelines: Optional[List[RetrieverPipeline]]

The pipelines this retriever uses.

description: Optional[str]

A description of the retriever tool.

maxLength15000
name: Optional[str]

A name for the retriever tool. Will default to the pipeline name if not provided.

maxLength3000
minLength1
pipeline_id: str

The ID of the pipeline this tool uses.

formatuuid
preset_retrieval_parameters: Optional[PresetRetrievalParams]

Parameters for retrieval configuration.

alpha: Optional[float]

Alpha value for hybrid retrieval to determine the weights between dense and sparse retrieval. 0 is sparse retrieval and 1 is dense retrieval.

maximum1
minimum0
class_name: Optional[str]
dense_similarity_cutoff: Optional[float]

Minimum similarity score wrt query for retrieval

maximum1
minimum0
dense_similarity_top_k: Optional[int]

Number of nodes for dense retrieval.

maximum100
minimum1
enable_reranking: Optional[bool]

Enable reranking for retrieval

files_top_k: Optional[int]

Number of files to retrieve (only for retrieval mode files_via_metadata and files_via_content).

maximum5
minimum1
rerank_top_n: Optional[int]

Number of reranked nodes for returning.

maximum100
minimum1
retrieval_mode: Optional[RetrievalMode]

The retrieval mode for the query.

One of the following:
"chunks"
"files_via_metadata"
"files_via_content"
"auto_routed"
Deprecatedretrieve_image_nodes: Optional[bool]

Whether to retrieve image nodes.

retrieve_page_figure_nodes: Optional[bool]

Whether to retrieve page figure nodes.

retrieve_page_screenshot_nodes: Optional[bool]

Whether to retrieve page screenshot nodes.

search_filters: Optional[MetadataFilters]

Metadata filters for vector stores.

filters: List[Filter]
One of the following:
class FilterMetadataFilter: …

Comprehensive metadata filter for vector stores to support more operators.

Value uses Strict types, as int, float and str are compatible types and were all converted to string before.

See: https://docs.pydantic.dev/latest/usage/types/#strict-types

key: str
value: Union[float, str, List[str], 3 more]
One of the following:
float
str
List[str]
List[float]
List[int]
operator: Optional[Literal["==", ">", "<", 11 more]]

Vector store filter operator.

One of the following:
"=="
">"
"<"
"!="
">="
"<="
"in"
"nin"
"any"
"all"
"text_match"
"text_match_insensitive"
"contains"
"is_empty"
condition: Optional[Literal["and", "or", "not"]]

Vector store filter conditions to combine different filters.

One of the following:
"and"
"or"
"not"
search_filters_inference_schema: Optional[Dict[str, Union[Dict[str, object], List[object], str, 3 more]]]

JSON Schema that will be used to infer search_filters. Omit or leave as null to skip inference.

One of the following:
Dict[str, object]
List[object]
str
float
bool
sparse_similarity_top_k: Optional[int]

Number of nodes for sparse retrieval.

maximum100
minimum1
updated_at: Optional[datetime]

Update datetime

formatdate-time

RetrieversRetriever

Retrieve
retrievers.retriever.search(strretriever_id, RetrieverSearchParams**kwargs) -> CompositeRetrievalResult
POST/api/v1/retrievers/{retriever_id}/retrieve