> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riggery.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Sheet map
> Outline a workbook, see where one sheet changes shape, or read the cells of a few rows.
On the graph, add **Sheet map**. On an agent, open **Files** and turn **Sheet map** on. It reads one file already stored on this Instance.
The result is an outline, a compressed map, or the cells of up to 100 rows. It is never the whole sheet. A script that needs every cell loads the grid itself: [Code](/graph/tools/code) with the same **File id**.
CSV, XLSX, and XLS are read in this step. The file type comes from its content, so an `.xls` saved with an `.xlsx` name still opens. PDF and Word use an extract that is already ready. This step does not start one. Call [Extract tables](/graph/tools/files-extract) first.
How it runs
One opaque id. Same rules as [Extract tables](/graph/tools/files-extract#file-id).
Empty **Sheet** lists every sheet: name, clipped rows and columns, how many rows have text, how many merged ranges. A sheet name returns that sheet's map, or its cells when **Rows** is set.
Rows with the same filled columns become one line (`from-to`). The line shows those columns (`cols=A-D,F`), the first values of its first row with their column letters, and the merged ranges that start in it. A header, a group row, or a row with a different set of filled columns stays its own line.
When the same pattern of lines repeats three times or more, for example one table per carrier or per port, the copies become one line. `6-17 repeats 1-5 x3` means rows 6 to 17 hold three more copies of the pattern in rows 1 to 5. Then it lists where each copy starts and its first values. A copy can have more or fewer rows than the first one.
Inspector **Settings**. Empty-field rules for the Graph: [Previous nodes](/graph/previous-nodes).
| Field | Required | Empty | Notes |
| - | - | - | - |
| **File id** | Yes | Fail | Opaque Instance file id. Not a filename. |
| **Sheet** | No | Outline | Sheet name. If several sheets match only by case, the step fails and lists the names. |
| **Rows** | No | Map | One row (`40`) or a range (`40-80`). Returns the cells of those rows instead of the map. At most 100 rows per call; a longer range is cut and the result says so. A range past the last row stops at the last row. |
Merged text stays on the top-left cell of the range. Other cells in the range are empty. The map names the range; it does not copy the text across it.
Empty trailing columns that the file marks as used are dropped. A sheet with no text fails. A sheet over 8000 rows, 64 columns, or 8000 merged ranges fails when you name it, and the error includes the counts. The outline still lists that sheet, and [Extract tables](/graph/tools/files-extract) still reads it.
PDF and Word add `warning: merges_unavailable`. Merged cells from those files are not listed.
Output
On the next node, **Previous nodes** lists **`Sheet map`: Result**.
| Output | In menu | Type | Next node gets |
| - | - | - | - |
| Result | Yes | Text | The outline, one sheet's map, or the cells of **Rows**. |
A long map is stored on the run. The model reads the rest with the result id from the tool result.
A map:
```text theme={null}
sheet: "Rates"
rows: 18
cols: 3
nonempty: 18
merges: 0
1-2 cols=A head="A:Rates"
3-5 cols=A-C head="A:POL | B:20GP | C:40HQ"
6-17 repeats 1-5 x3: 6 "A:Shanghai", 10 "A:Qingdao", 14 "A:Xiamen"
18 cols=A-B head="A:Notes | B:x"
```
The same sheet with **Rows** `2-4`:
```text theme={null}
sheet: "Rates"
rows: 2-4
2: A="Ningbo"
3: A="POL" B="20GP" C="40HQ"
4: A="Moscow" B="10" C="20"
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.