---
title: File Operations | Developer Documentation
description: Search for files, grep within parsed content, and read file text from an index.
---

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.retrieval.*` in the SDK.

Tip

MCP-compatible agents get the same capabilities through the `findFilesInIndex`, `grepFileFromIndex`, and `readFileFromIndex` tools of the [LlamaParse MCP](../../for-agents/mcp/).

## Find files

Find files by exact name or substring match.

- [Python](#tab-panel-145)
- [TypeScript](#tab-panel-146)
- [Go](#tab-panel-147)
- [Java](#tab-panel-148)
- [CLI](#tab-panel-149)

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


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


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

```
// Substring match
const results = await client.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}`);
}
```

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


// Substring match (case-insensitive)
page, err = client.Retrieval.Find(ctx, llamacloud.RetrievalFindParams{
  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)
}
```

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


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


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

Terminal window

```
# 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 '"\(.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](#tab-panel-150)
- [TypeScript](#tab-panel-151)
- [Go](#tab-panel-152)
- [Java](#tab-panel-153)
- [CLI](#tab-panel-154)

```
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.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}")
```

```
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.grep({
  index_id: "<your-index-id>",
  file_id: fileId,
  pattern: "revenue|profit",
  context_chars: 100,
});


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

```
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


page, err := client.Retrieval.Grep(ctx, llamacloud.RetrievalGrepParams{
  IndexID:      "<your-index-id>",
  FileID:       fileID,
  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)
}
```

```
import ai.llamaindex.llamacloud.models.retrieval.RetrievalFindPage;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalFindParams;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalGrepPage;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalGrepParams;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalGrepResponse;


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();


RetrievalGrepPage results = client.retrieval().grep(
    RetrievalGrepParams.builder()
        .indexId("<your-index-id>")
        .fileId(fileId)
        .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());
}
```

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 grep \
    --index-id "<your-index-id>" \
    --file-id "$FILE_ID" \
    --pattern "revenue|profit" \
    --context-chars 100 \
    | jq -r '"Offset \(.start_char)-\(.end_char): \(.content)"'
fi
```

### 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](#tab-panel-155)
- [TypeScript](#tab-panel-156)
- [Go](#tab-panel-157)
- [Java](#tab-panel-158)
- [CLI](#tab-panel-159)

```
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


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


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

```
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;


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


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

```
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


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


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

```
import ai.llamaindex.llamacloud.models.retrieval.RetrievalFindPage;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalFindParams;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalReadParams;
import ai.llamaindex.llamacloud.models.retrieval.RetrievalReadResponse;


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();


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


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

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
  # 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'
fi
```

### 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. |