Core concepts
Workbook Mental Model
Understand how workbooks, worksheets, rows, cells, ranges, and metadata fit together.
One file, a hierarchy of spreadsheet objects.
Start with the object you need to work with. Most application code lives at the worksheet, row, or cell level; the workbook coordinates the file as a whole.
- 01
Workbook
The complete spreadsheet file and its collection of sheets.
Open, inspect, create, save - 02
Worksheet
A named grid such as
Select sheets and access their contentOrders,Summary, orConfig. - 03
Row
An ordered record—usually the natural shape for imports and business data.
Headers, iteration, chunks, projection - 04
Cell
One coordinate with a value plus optional formula, format, link, comment, and style.
Direct lookup and rich inspection
Rows for records. Cells for coordinates and rich detail.
The model is the same either way. Choose the API shape that matches the work your application is doing.
Process business records in sequence.
Best for imports, exports, validation pipelines, projections, and large one-pass reads.
rows()chunks()withHeaderRow()Address exact workbook locations.
Best for configuration sheets, targeted lookups, formulas, styles, comments, images, and metadata.
cell()cells()rangeValues()cellDetails()- Business records and imports
rows(),chunks(), headers, projection- Lookup or configuration cells
cell(),cells(),rangeValues()- Rich workbook inspection
cellDetails(), styles, images, metadata- Pre-read package inspection
inspect(),sheetNames(),countRows()- Output composition
WorkbookBuilder
Values are only one layer of a workbook.
Ranges connect cells into meaningful regions, while metadata preserves how those cells behave and appear.
A1:F20A rectangular group of cells.
Styling, filters, validation, charts, conditional formatting, and pivots commonly refer to ranges rather than individual coordinates.
Meaning can live beside the displayed value.
Use a detailed snapshot when your application needs more than plain values.
- Original type
- Formula
- Cached result
- Number format
- Hyperlink
- Comment
- Rich text
- Protection
- Merged-range membership