File Operations

File operations let you work with individual files inside an index. You can search for files by name, grep through their parsed content with regex, and read the full text of a file — all without needing to access the original documents.

These endpoints are available under client.beta.retrieval.* in the SDK.

Tip

MCP-compatible agents get the same capabilities through the findFilesInIndex, grepFileFromIndex, and readFileFromIndex tools of the LlamaParse MCP.

Find files

Find files by exact name or substring match.

Python

# Exact name match
results = await client.beta.retrieval.find(
    index_id="<your-index-id>",
    file_name="quarterly-report.pdf",
)

# Substring match (case-insensitive)
results = await client.beta.retrieval.find(
    index_id="<your-index-id>",
    file_name_contains="quarterly",
)

for f in results.items:
    print(f"{f.file_id}: {f.file_name}")

TypeScript

// Substring match
const results = await client.beta.retrieval.find({
  index_id: "<your-index-id>",
  file_name_contains: "quarterly",
});

for (const f of results.items) {
  console.log(`${f.file_id}: ${f.file_name}`);
}

Go

// Exact name match
page, err := client.Beta.Retrieval.Find(ctx, llamacloud.BetaRetrievalFindParams{
  IndexID:  "<your-index-id>",
  FileName: llamacloud.String("quarterly-report.pdf"),
})
if err != nil {
  log.Fatal(err)
}

// Substring match (case-insensitive)
page, err = client.Beta.Retrieval.Find(ctx, llamacloud.BetaRetrievalFindParams{
  IndexID:          "<your-index-id>",
  FileNameContains: llamacloud.String("quarterly"),
})
if err != nil {
  log.Fatal(err)
}

for _, f := range page.Items {
  fmt.Printf("%s: %s\n", f.FileID, f.FileName)
}

Java

import ai.llamaindex.llamacloud.models.beta.retrieval.RetrievalFindPage;
import ai.llamaindex.llamacloud.models.beta.retrieval.RetrievalFindParams;
import ai.llamaindex.llamacloud.models.beta.retrieval.RetrievalFindResponse;

// Substring match (case-insensitive)
RetrievalFindPage results = client.beta().retrieval().find(
    RetrievalFindParams.builder()
        .indexId("<your-index-id>")
        .fileNameContains("quarterly")
        .build());

for (RetrievalFindResponse f : results.items()) {
    System.out.println(f.fileId() + ": " + f.fileName());
}

CLI

# Exact name match
llp beta:retrieval find \
  --index-id "<your-index-id>" \
  --file-name "quarterly-report.pdf"

# Substring match (case-insensitive)
llp beta:retrieval find \
  --index-id "<your-index-id>" \
  --file-name-contains "quarterly" \
  | jq -r '.items[] | "\(.file_id): \(.file_name)"'

Grep within a file

Search for a regex pattern within a file’s parsed text content. This is useful for finding specific terms, patterns, or sections within a document.

Python

results = await client.beta.retrieval.grep(
    index_id="<your-index-id>",
    file_id="<file-id>",
    pattern="revenue|profit",
    context_chars=100,  # characters of context around each match
)

for match in results.items:
    print(f"Offset {match.start_char}-{match.end_char}: {match.content}")

TypeScript

const results = await client.beta.retrieval.grep({
  index_id: "<your-index-id>",
  file_id: "<file-id>",
  pattern: "revenue|profit",
  context_chars: 100,
});

for (const match of results.items) {
  console.log(`Offset ${match.start_char}-${match.end_char}: ${match.content}`);
}

Go

page, err := client.Beta.Retrieval.Grep(ctx, llamacloud.BetaRetrievalGrepParams{
  IndexID:      "<your-index-id>",
  FileID:       "<file-id>",
  Pattern:      "revenue|profit",
  ContextChars: llamacloud.Int(100), // characters of context around each match
})
if err != nil {
  log.Fatal(err)
}

for _, match := range page.Items {
  fmt.Printf("Offset %d-%d: %s\n", match.StartChar, match.EndChar, match.Content)
}

Java

import ai.llamaindex.llamacloud.models.beta.retrieval.RetrievalGrepPage;
import ai.llamaindex.llamacloud.models.beta.retrieval.RetrievalGrepParams;
import ai.llamaindex.llamacloud.models.beta.retrieval.RetrievalGrepResponse;

RetrievalGrepPage results = client.beta().retrieval().grep(
    RetrievalGrepParams.builder()
        .indexId("<your-index-id>")
        .fileId("<file-id>")
        .pattern("revenue|profit")
        .contextChars(100) // characters of context around each match
        .build());

for (RetrievalGrepResponse match : results.items()) {
    System.out.println("Offset " + match.startChar() + "-" + match.endChar() + ": " + match.content());
}

CLI

llp beta:retrieval grep \
  --index-id "<your-index-id>" \
  --file-id "<file-id>" \
  --pattern "revenue|profit" \
  --context-chars 100 \
  | jq -r '.items[] | "Offset \(.start_char)-\(.end_char): \(.content)"'

Grep parameters

Parameter	Type	Default	Description
index_id	string	required	ID of the index.
file_id	string	required	ID of the file to search within.
pattern	string	required	Regex pattern to match.
context_chars	int	null	Characters of context to include around each match.

Read a file

Read the parsed text content of a file. Supports pagination via offset and max_length for large documents.

Python

# Read the full file
result = await client.beta.retrieval.read(
    index_id="<your-index-id>",
    file_id="<file-id>",
)
print(result.content)

# Read a specific range
result = await client.beta.retrieval.read(
    index_id="<your-index-id>",
    file_id="<file-id>",
    offset=1000,
    max_length=5000,
)
print(result.content)

TypeScript

// Read the full file
const result = await client.beta.retrieval.read({
  index_id: "<your-index-id>",
  file_id: "<file-id>",
});
console.log(result.content);

// Read a specific range
const partial = await client.beta.retrieval.read({
  index_id: "<your-index-id>",
  file_id: "<file-id>",
  offset: 1000,
  max_length: 5000,
});
console.log(partial.content);

Go

// Read the full file
result, err := client.Beta.Retrieval.Read(ctx, llamacloud.BetaRetrievalReadParams{
  IndexID: "<your-index-id>",
  FileID:  "<file-id>",
})
if err != nil {
  log.Fatal(err)
}
fmt.Println(result.Content)

// Read a specific range
partial, err := client.Beta.Retrieval.Read(ctx, llamacloud.BetaRetrievalReadParams{
  IndexID:   "<your-index-id>",
  FileID:    "<file-id>",
  Offset:    llamacloud.Int(1000),
  MaxLength: llamacloud.Int(5000),
})
if err != nil {
  log.Fatal(err)
}
fmt.Println(partial.Content)

Java

import ai.llamaindex.llamacloud.models.beta.retrieval.RetrievalReadParams;
import ai.llamaindex.llamacloud.models.beta.retrieval.RetrievalReadResponse;

// Read the full file
RetrievalReadResponse result = client.beta().retrieval().read(
    RetrievalReadParams.builder()
        .indexId("<your-index-id>")
        .fileId("<file-id>")
        .build());
System.out.println(result.content());

// Read a specific range
RetrievalReadResponse partial = client.beta().retrieval().read(
    RetrievalReadParams.builder()
        .indexId("<your-index-id>")
        .fileId("<file-id>")
        .offset(1000)
        .maxLength(5000)
        .build());
System.out.println(partial.content());

CLI

# Read the full file
llp beta:retrieval read \
  --index-id "<your-index-id>" \
  --file-id "<file-id>" \
  | jq -r '.content'

# Read a specific range
llp beta:retrieval read \
  --index-id "<your-index-id>" \
  --file-id "<file-id>" \
  --offset 1000 \
  --max-length 5000 \
  | jq -r '.content'

Read parameters

Parameter	Type	Default	Description
index_id	string	required	ID of the index.
file_id	string	required	ID of the file to read.
offset	int	0	Starting character offset.
max_length	int	null	Maximum characters to return from the offset. Returns the full file if omitted.