Retrieve

client.beta.retrieval.retrieve(, ?): RetrievalRetrieveResponse { results }

POST/api/v1/retrieval/retrieve

Retrieve relevant chunks via hybrid search (vector + full-text), with filtering on built-in or user-defined metadata.

ParametersExpand Collapse

params: RetrievalRetrieveParams { index_id, query, organization_id, 9 more }

index_id: string

Body param: ID of the index to retrieve against.

query: string

Body param: Natural-language query to retrieve relevant chunks.

organization_id?: string | null

Query param

formatuuid

project_id?: string | null

Query param

formatuuid

custom_filters?: Record<string, FilterTypeUnionStrIntBoolFloat { operator, value } | Array<UnionMember1> | null> | null

Body param: Filters on user-defined metadata fields.

One of the following:

FilterTypeUnionStrIntBoolFloat { operator, value }

operator: "eq" | "ne" | "gt" | 5 more

One of the following:

"eq"

"ne"

"gt"

"lt"

"gte"

"lte"

"in"

"nin"

One of the following:

string

boolean

number

Array<string | boolean | number>

string

boolean

number

Array<UnionMember1>

operator: "eq" | "ne" | "gt" | 5 more

One of the following:

"eq"

"ne"

"gt"

"lt"

"gte"

"lte"

"in"

"nin"

value: number | Array<number>

One of the following:

number

Array<number>

full_text_pipeline_weight?: number | null

Body param: Weight of the full-text search pipeline (0-1).

num_candidates?: number | null

Body param: Number of candidates for approximate nearest neighbor search.

rerank?: Rerank

Body param: Reranking configuration applied after hybrid search. Enabled by default.

enabled?: boolean

Set to false to disable reranking.

top_n?: number | null

Number of results to return after reranking.

score_threshold?: number | null

Body param: Minimum score threshold for returned results.

static_filters?: StaticFilters | null

Body param: Filters on built-in document fields (page range, chunk index, etc.).

parsed_directory_file_id?: ParsedDirectoryFileID | null

operator: "eq" | "ne" | "gt" | 5 more

One of the following:

"eq"

"ne"

"gt"

"lt"

"gte"

"lte"

"in"

"nin"

value: string | Array<string>

One of the following:

string

Array<string>

top_k?: number | null

Body param: Maximum number of results to return.

vector_pipeline_weight?: number | null

Body param: Weight of the vector search pipeline (0-1).

ReturnsExpand Collapse

RetrievalRetrieveResponse { results }

Response containing retrieval results.

results: Array<Result>

Ordered list of retrieved chunks.

content: string

Text content of the retrieved chunk.

User-defined metadata associated with the chunk.

One of the following:

string

number

boolean

Array<string>

rerank_score?: number | null

Relevance score from the reranker, if reranking was applied.

score?: number | null

Hybrid search relevance score.

static_fields?: StaticFields { attachments, chunk_end_char, chunk_index, 5 more }

Built-in fields stored for every exported chunk.

attachments?: Array<Attachment>

Attachments associated with the chunk

attachment_name: string

Attachment-relative path, e.g. ‘screenshots/page_7.jpg’.

source_id: string

File ID to pass as source_id when fetching the attachment.

type: string

Attachment kind, e.g. ‘screenshot’, ‘items’.

chunk_end_char?: number | null

End character offset of the chunk.

chunk_index?: number | null

Index of the chunk within the file.

chunk_start_char?: number | null

Start character offset of the chunk.

chunk_token_count?: number | null

Token count of the chunk.

page_range_end?: number | null

Last page number covered by this chunk.

page_range_start?: number | null

First page number covered by this chunk.

parsed_directory_file_id?: string | null

ID of the parsed file.

Retrieve

import LlamaCloud from '@llamaindex/llama-cloud';

const client = new LlamaCloud({
  apiKey: process.env['LLAMA_CLOUD_API_KEY'], // This is the default and can be omitted
});

const retrieval = await client.beta.retrieval.retrieve({
  index_id: 'idx-abc123',
  query: 'What are the key findings?',
});

console.log(retrieval.results);

{
  "results": [
    {
      "content": "content",
      "metadata": {
        "foo": "string"
      },
      "rerank_score": 0,
      "score": 0,
      "static_fields": {
        "attachments": [
          {
            "attachment_name": "attachment_name",
            "source_id": "source_id",
            "type": "type"
          }
        ],
        "chunk_end_char": 0,
        "chunk_index": 0,
        "chunk_start_char": 0,
        "chunk_token_count": 0,
        "page_range_end": 0,
        "page_range_start": 0,
        "parsed_directory_file_id": "parsed_directory_file_id"
      }
    }
  ]
}

Returns Examples

{
  "results": [
    {
      "content": "content",
      "metadata": {
        "foo": "string"
      },
      "rerank_score": 0,
      "score": 0,
      "static_fields": {
        "attachments": [
          {
            "attachment_name": "attachment_name",
            "source_id": "source_id",
            "type": "type"
          }
        ],
        "chunk_end_char": 0,
        "chunk_index": 0,
        "chunk_start_char": 0,
        "chunk_token_count": 0,
        "page_range_end": 0,
        "page_range_start": 0,
        "parsed_directory_file_id": "parsed_directory_file_id"
      }
    }
  ]
}