Retrieval

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, with no SDK code required.

Basic retrieval

Python

results = await client.beta.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)

TypeScript

const results = await client.beta.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);
}

Go

results, err := client.Beta.Retrieval.Get(ctx, llamacloud.BetaRetrievalGetParams{
  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)
}

Java

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

RetrievalRetrieveResponse results = client.beta().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());
}

CLI

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

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

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

TypeScript

// Disable reranking
const results = await client.beta.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.beta.retrieval.retrieve({
  index_id: "<your-index-id>",
  query: "summary of findings",
  rerank: { enabled: true, top_n: 3 },
});

Go

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

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

Java

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

// Disable reranking
RetrievalRetrieveResponse results = client.beta().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.beta().retrieval().retrieve(
    RetrievalRetrieveParams.builder()
        .indexId("<your-index-id>")
        .query("summary of findings")
        .rerank(RetrievalRetrieveParams.Rerank.builder()
            .enabled(true)
            .topN(3)
            .build())
        .build());

CLI

# 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

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

TypeScript

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

Go

results, err := client.Beta.Retrieval.Get(ctx, llamacloud.BetaRetrievalGetParams{
  IndexID: "<your-index-id>",
  Query:   "revenue breakdown",
  StaticFilters: llamacloud.BetaRetrievalGetParamsStaticFilters{
    ParsedDirectoryFileID: llamacloud.BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileID{
      Operator: "eq",
      Value: llamacloud.BetaRetrievalGetParamsStaticFiltersParsedDirectoryFileIDValueUnion{
        OfString: llamacloud.String("<file-id>"),
      },
    },
  },
})
if err != nil {
  log.Fatal(err)
}

Java

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

RetrievalRetrieveResponse results = client.beta().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("<file-id>")
                .build())
            .build())
        .build());

CLI

llp beta:retrieval retrieve \
  --index-id "<your-index-id>" \
  --query "revenue breakdown" \
  --static-filters '{"parsed_directory_file_id": {"operator": "eq", "value": "<file-id>"}}'

Custom metadata filters

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

Python

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

TypeScript

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

Go

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

Java

import java.util.Map;

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

RetrievalRetrieveResponse results = client.beta().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());

CLI

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.