---
title: Retrieval | Developer Documentation
description: Hybrid search over indexed documents with vector search, full-text search, filtering, and reranking.
---

The retrieval endpoint performs hybrid search combining vector similarity and full-text search. Results can be filtered by built-in fields or user-defined metadata, and reranked for higher relevance.

Tip

MCP-compatible agents can run the same hybrid retrieval through the `retrieveFromIndex` tool of the [LlamaParse MCP](../../for-agents/mcp/), with no SDK code required.

## Basic retrieval

- [Python](#tab-panel-190)
- [TypeScript](#tab-panel-191)
- [Go](#tab-panel-192)
- [Java](#tab-panel-193)
- [CLI](#tab-panel-194)

```
results = await client.retrieval.retrieve(
    index_id="<your-index-id>",
    query="What were the Q3 revenue figures?",
    top_k=10,
)


for result in results.results:
    print(f"Score: {result.score}, Rerank: {result.rerank_score}")
    print(result.content)
```

```
const results = await client.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "What were the Q3 revenue figures?",
  top_k: 10,
});


for (const result of results.results) {
  console.log(`Score: ${result.score}, Rerank: ${result.rerank_score}`);
  console.log(result.content);
}
```

```
results, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "What were the Q3 revenue figures?",
  TopK:    llamacloud.Int(10),
})
if err != nil {
  log.Fatal(err)
}


for _, result := range results.Results {
  fmt.Printf("Score: %v, Rerank: %v\n", result.Score, result.RerankScore)
  fmt.Println(result.Content)
}
```

```
import ai.llamaindex.llamacloud.models.retrieval.RetrievalRetrieveParams;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalRetrieveResponse;


RetrievalRetrieveResponse results = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("What were the Q3 revenue figures?")
        .topK(10)
        .build());


for (RetrievalRetrieveResponse.Result result : results.results()) {
    System.out.println("Score: " + result.score().orElse(null)
        + ", Rerank: " + result.rerankScore().orElse(null));
    System.out.println(result.content());
}
```

Terminal window

```
llp beta:retrieval retrieve \
  --index-id "<your-index-id>" \
  --query "What were the Q3 revenue figures?" \
  --top-k 10 \
  | jq -r '.results[] | "Score: \(.score), Rerank: \(.rerank_score)\n\(.content)"'
```

## Parameters

| Parameter                   | Type     | Default        | Description                                                   |
| --------------------------- | -------- | -------------- | ------------------------------------------------------------- |
| `index_id`                  | `string` | *required*     | ID of the index to retrieve against.                          |
| `query`                     | `string` | *required*     | Natural-language query.                                       |
| `top_k`                     | `int`    | server default | Maximum number of results to return.                          |
| `vector_pipeline_weight`    | `float`  | `null`         | Weight for vector search (0—1).                               |
| `full_text_pipeline_weight` | `float`  | `null`         | Weight for full-text search (0—1).                            |
| `score_threshold`           | `float`  | `null`         | Minimum score for returned results.                           |
| `num_candidates`            | `int`    | `null`         | Number of ANN candidates (higher = more accurate but slower). |

## Reranking

Reranking is **enabled by default**. After hybrid search retrieves candidates, a reranker model re-scores them for improved relevance.

- [Python](#tab-panel-195)
- [TypeScript](#tab-panel-196)
- [Go](#tab-panel-197)
- [Java](#tab-panel-198)
- [CLI](#tab-panel-199)

```
# Disable reranking
results = await client.retrieval.retrieve(
    index_id="<your-index-id>",
    query="summary of findings",
    rerank={"enabled": False},
)


# Keep reranking but limit to top 3
results = await client.retrieval.retrieve(
    index_id="<your-index-id>",
    query="summary of findings",
    rerank={"enabled": True, "top_n": 3},
)
```

```
// Disable reranking
const results = await client.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "summary of findings",
  rerank: { enabled: false },
});


// Keep reranking but limit to top 3
const results2 = await client.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "summary of findings",
  rerank: { enabled: true, top_n: 3 },
});
```

```
// Disable reranking
results, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "summary of findings",
  Rerank:  llamacloud.RetrievalGetParamsRerank{Enabled: llamacloud.Bool(false)},
})
if err != nil {
  log.Fatal(err)
}


// Keep reranking but limit to top 3
results2, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "summary of findings",
  Rerank:  llamacloud.RetrievalGetParamsRerank{Enabled: llamacloud.Bool(true), TopN: llamacloud.Int(3)},
})
if err != nil {
  log.Fatal(err)
}
```

```
import ai.llamaindex.llamacloud.models.retrieval.RetrievalRetrieveParams;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalRetrieveResponse;


// Disable reranking
RetrievalRetrieveResponse results = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("summary of findings")
        .rerank(RetrievalRetrieveParams.Rerank.builder()
            .enabled(false)
            .build())
        .build());


// Keep reranking but limit to top 3
RetrievalRetrieveResponse results2 = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("summary of findings")
        .rerank(RetrievalRetrieveParams.Rerank.builder()
            .enabled(true)
            .topN(3)
            .build())
        .build());
```

Terminal window

```
# Disable reranking
llp beta:retrieval retrieve \
  --index-id "<your-index-id>" \
  --query "summary of findings" \
  --rerank '{"enabled": false}'


# Keep reranking but limit to top 3
llp beta:retrieval retrieve \
  --index-id "<your-index-id>" \
  --query "summary of findings" \
  --rerank '{"enabled": true, "top_n": 3}'
```

## Filtering

You can filter results using built-in static fields (page range, chunk index) or user-defined custom metadata.

### Static filters

Static filters operate on built-in fields stored for every chunk. Currently the supported field is `parsed_directory_file_id`, which lets you scope retrieval to specific files.

- [Python](#tab-panel-200)
- [TypeScript](#tab-panel-201)
- [Go](#tab-panel-202)
- [Java](#tab-panel-203)
- [CLI](#tab-panel-204)

```
found = await client.retrieval.find(
    index_id="<your-index-id>",
    file_name="quarterly-report.pdf",
)
if not found.items:
    raise SystemExit("quarterly-report.pdf is not in the index")
file_id = found.items[0].file_id


results = await client.retrieval.retrieve(
    index_id="<your-index-id>",
    query="revenue breakdown",
    static_filters={
        "parsed_directory_file_id": {"operator": "eq", "value": file_id},
    },
)
```

```
const found = await client.retrieval.find({
  index_id: "<your-index-id>",
  file_name: "quarterly-report.pdf",
});
if (found.items.length === 0) {
  throw new Error("quarterly-report.pdf is not in the index");
}
const fileId = found.items[0].file_id;


const results = await client.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "revenue breakdown",
  static_filters: {
    parsed_directory_file_id: { operator: "eq", value: fileId },
  },
});
```

```
found, err := client.Retrieval.Find(ctx, llamacloud.RetrievalFindParams{
  IndexID:  "<your-index-id>",
  FileName: llamacloud.String("quarterly-report.pdf"),
})
if err != nil {
  log.Fatal(err)
}
if len(found.Items) == 0 {
  log.Fatal("quarterly-report.pdf is not in the index")
}
fileID := found.Items[0].FileID


results, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "revenue breakdown",
  StaticFilters: llamacloud.RetrievalGetParamsStaticFilters{
    ParsedDirectoryFileID: llamacloud.RetrievalGetParamsStaticFiltersParsedDirectoryFileID{
      Operator: "eq",
      Value: llamacloud.RetrievalGetParamsStaticFiltersParsedDirectoryFileIDValueUnion{
        OfString: llamacloud.String(fileID),
      },
    },
  },
})
if err != nil {
  log.Fatal(err)
}
```

```
import ai.llamaindex.llamacloud.models.retrieval.RetrievalFindPage;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalFindParams;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalRetrieveParams;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalRetrieveResponse;


RetrievalFindPage found = client.retrieval().find(
    RetrievalFindParams.builder()
        .indexId("<your-index-id>")
        .fileName("quarterly-report.pdf")
        .build());
if (found.items().isEmpty()) {
    throw new IllegalStateException("quarterly-report.pdf is not in the index");
}
String fileId = found.items().get(0).fileId();


RetrievalRetrieveResponse results = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("revenue breakdown")
        .staticFilters(RetrievalRetrieveParams.StaticFilters.builder()
            .parsedDirectoryFileId(RetrievalRetrieveParams.StaticFilters.ParsedDirectoryFileId.builder()
                .operator(RetrievalRetrieveParams.StaticFilters.ParsedDirectoryFileId.Operator.EQ)
                .value(fileId)
                .build())
            .build())
        .build());
```

Terminal window

```
FILE_ID=$(llp beta:retrieval find \
  --index-id "<your-index-id>" \
  --file-name "quarterly-report.pdf" \
  --max-items 1 \
  | jq -r '.file_id // empty')
if [ -z "$FILE_ID" ]; then
  echo "could not find quarterly-report.pdf in the index" >&2
else
  llp beta:retrieval retrieve \
    --index-id "<your-index-id>" \
    --query "revenue breakdown" \
    --static-filters "$(jq -cn --arg id "$FILE_ID" '{parsed_directory_file_id: {operator: "eq", value: $id}}')"
fi
```

### Custom metadata filters

Custom filters match against user-defined metadata that was attached to files when they were added to the directory.

- [Python](#tab-panel-205)
- [TypeScript](#tab-panel-206)
- [Go](#tab-panel-207)
- [Java](#tab-panel-208)
- [CLI](#tab-panel-209)

```
results = await client.retrieval.retrieve(
    index_id="<your-index-id>",
    query="contract terms",
    custom_filters={
        "category": {"operator": "eq", "value": "legal"},
        "year": {"operator": "gte", "value": 2024},
    },
)
```

```
const results = await client.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "contract terms",
  custom_filters: {
    category: { operator: "eq", value: "legal" },
    year: { operator: "gte", value: 2024 },
  },
});
```

```
results, err := client.Retrieval.Get(ctx, llamacloud.RetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "contract terms",
  CustomFilters: map[string]*llamacloud.RetrievalGetParamsCustomFilterUnion{
    "category": {
      OfValueFilter: &llamacloud.RetrievalGetParamsCustomFilterValueFilter{
        Operator: "eq",
        Value: llamacloud.RetrievalGetParamsCustomFilterValueFilterValueUnion{
          OfString: llamacloud.String("legal"),
        },
      },
    },
    "year": {
      OfValueFilter: &llamacloud.RetrievalGetParamsCustomFilterValueFilter{
        Operator: "gte",
        Value: llamacloud.RetrievalGetParamsCustomFilterValueFilterValueUnion{
          OfFloat: llamacloud.Float(2024),
        },
      },
    },
  },
})
if err != nil {
  log.Fatal(err)
}
```

```
import java.util.Map;


import ai.llamaindex.llamacloud.core.JsonValue;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalRetrieveParams;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalRetrieveResponse;


RetrievalRetrieveResponse results = client.retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("contract terms")
        .customFilters(RetrievalRetrieveParams.CustomFilters.builder()
            .putAdditionalProperty("category", JsonValue.from(Map.of("operator", "eq", "value", "legal")))
            .putAdditionalProperty("year", JsonValue.from(Map.of("operator", "gte", "value", 2024)))
            .build())
        .build());
```

Terminal window

```
llp beta:retrieval retrieve \
  --index-id "<your-index-id>" \
  --query "contract terms" \
  --custom-filters '{"category": {"operator": "eq", "value": "legal"}, "year": {"operator": "gte", "value": 2024}}'
```

## Response format

Each result in the response contains:

| Field                                               | Description                                         |
| --------------------------------------------------- | --------------------------------------------------- |
| `content`                                           | The text content of the retrieved chunk.            |
| `score`                                             | Hybrid search relevance score.                      |
| `rerank_score`                                      | Score from the reranker (if reranking was applied). |
| `metadata`                                          | User-defined metadata associated with the chunk.    |
| `static_fields.parsed_directory_file_id`            | ID of the parsed file this chunk belongs to.        |
| `static_fields.page_range_start` / `page_range_end` | Page numbers covered by the chunk.                  |
| `static_fields.chunk_index`                         | Position of the chunk within the file.              |
| `static_fields.chunk_token_count`                   | Token count of the chunk.                           |