# Retrieval ## Retrieve `client.beta.retrieval.retrieve(RetrievalRetrieveParamsparams, RequestOptionsoptions?): RetrievalRetrieveResponse` **post** `/api/v1/retrieval/retrieve` Retrieve relevant chunks via hybrid search (vector + full-text), with filtering on built-in or user-defined metadata. ### Parameters - `params: RetrievalRetrieveParams` - `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 - `project_id?: string | null` Query param - `custom_filters?: Record | null> | null` Body param: Filters on user-defined metadata fields. - `FilterTypeUnionStrIntBoolFloat` - `operator: "eq" | "ne" | "gt" | 5 more` - `"eq"` - `"ne"` - `"gt"` - `"lt"` - `"gte"` - `"lte"` - `"in"` - `"nin"` - `value: string | boolean | number | Array` - `string` - `boolean` - `number` - `Array` - `string` - `boolean` - `number` - `Array` - `operator: "eq" | "ne" | "gt" | 5 more` - `"eq"` - `"ne"` - `"gt"` - `"lt"` - `"gte"` - `"lte"` - `"in"` - `"nin"` - `value: number | Array` - `number` - `Array` - `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` - `"eq"` - `"ne"` - `"gt"` - `"lt"` - `"gte"` - `"lte"` - `"in"` - `"nin"` - `value: string | Array` - `string` - `Array` - `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). ### Returns - `RetrievalRetrieveResponse` Response containing retrieval results. - `results: Array` Ordered list of retrieved chunks. - `content: string` Text content of the retrieved chunk. - `metadata?: Record | null> | null` User-defined metadata associated with the chunk. - `string` - `number` - `boolean` - `Array` - `rerank_score?: number | null` Relevance score from the reranker, if reranking was applied. - `score?: number | null` Hybrid search relevance score. - `static_fields?: StaticFields` Built-in fields stored for every exported chunk. - `attachments?: Array` 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. ### Example ```typescript 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); ``` #### Response ```json { "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" } } ] } ``` ## Search Files `client.beta.retrieval.search(RetrievalSearchParamsparams, RequestOptionsoptions?): RetrievalSearchResponse` **post** `/api/v1/retrieval/files/search` Search for files by name. ### Parameters - `params: RetrievalSearchParams` - `index_id: string` Body param: ID of the index to search within. - `organization_id?: string | null` Query param - `project_id?: string | null` Query param - `file_name?: string | null` Body param: Exact file name to match. - `file_name_contains?: string | null` Body param: Substring match on file name (case-insensitive). - `limit?: number | null` Body param: Maximum number of files to return. ### Returns - `RetrievalSearchResponse` File search results. - `files: Array` Matching files with names. - `file_id: string` ID of the file. - `file_name: string` Display name of the file. ### Example ```typescript 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 response = await client.beta.retrieval.search({ index_id: 'idx-abc123' }); console.log(response.files); ``` #### Response ```json { "files": [ { "file_id": "file_id", "file_name": "file_name" } ] } ``` ## Grep File `client.beta.retrieval.grep(RetrievalGrepParamsparams, RequestOptionsoptions?): RetrievalGrepResponse` **post** `/api/v1/retrieval/files/grep` Grep within a file's parsed content using a regex pattern. ### Parameters - `params: RetrievalGrepParams` - `file_id: string` Body param: ID of the file to grep. - `index_id: string` Body param: ID of the index the file belongs to. - `pattern: string` Body param: Regex pattern to search for. - `organization_id?: string | null` Query param - `project_id?: string | null` Query param - `context_chars?: number | null` Body param: Number of characters of context to include before and after the matched pattern in the content field of the response - `limit?: number | null` Body param: Maximum number of matches to return. ### Returns - `RetrievalGrepResponse` Grep results for a file. - `matches: Array` Regex matches found in the file. - `content: string` Matched text content. - `end_char: number` End character offset of the match. - `start_char: number` Start character offset of the match. ### Example ```typescript 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 response = await client.beta.retrieval.grep({ file_id: 'file_id', index_id: 'idx-abc123', pattern: 'revenue|profit', }); console.log(response.matches); ``` #### Response ```json { "matches": [ { "content": "content", "end_char": 0, "start_char": 0 } ] } ``` ## Read File `client.beta.retrieval.read(RetrievalReadParamsparams, RequestOptionsoptions?): RetrievalReadResponse` **post** `/api/v1/retrieval/files/read` Read the parsed text content of a specific file. ### Parameters - `params: RetrievalReadParams` - `file_id: string` Body param: ID of the file to read. - `index_id: string` Body param: ID of the index the file belongs to. - `organization_id?: string | null` Query param - `project_id?: string | null` Query param - `max_length?: number | null` Body param: Maximum number of characters to read from the offset. - `offset?: number` Body param: Starting character offset. ### Returns - `RetrievalReadResponse` File read result. - `content: string` Parsed text content of the file. ### Example ```typescript 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 response = await client.beta.retrieval.read({ file_id: 'file_id', index_id: 'idx-abc123' }); console.log(response.content); ``` #### Response ```json { "content": "content" } ``` ## Domain Types ### Retrieval Retrieve Response - `RetrievalRetrieveResponse` Response containing retrieval results. - `results: Array` Ordered list of retrieved chunks. - `content: string` Text content of the retrieved chunk. - `metadata?: Record | null> | null` User-defined metadata associated with the chunk. - `string` - `number` - `boolean` - `Array` - `rerank_score?: number | null` Relevance score from the reranker, if reranking was applied. - `score?: number | null` Hybrid search relevance score. - `static_fields?: StaticFields` Built-in fields stored for every exported chunk. - `attachments?: Array` 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. ### Retrieval Search Response - `RetrievalSearchResponse` File search results. - `files: Array` Matching files with names. - `file_id: string` ID of the file. - `file_name: string` Display name of the file. ### Retrieval Grep Response - `RetrievalGrepResponse` Grep results for a file. - `matches: Array` Regex matches found in the file. - `content: string` Matched text content. - `end_char: number` End character offset of the match. - `start_char: number` Start character offset of the match. ### Retrieval Read Response - `RetrievalReadResponse` File read result. - `content: string` Parsed text content of the file.