Walking The Hierarchy

Why every Apps Script reads as a chain

Apps Script code is full of lines like spreadsheet.getSheetByName(“X”).getRange(“A1:C10”).getValues(). That chain isn’t style — it’s the API forcing the developer to walk from “the whole document” down to “the specific piece of data.” Each step hands back a different kind of object with its own methods, and the developer has to keep narrowing until the call returns actual data.

The Sheets hierarchy

The path from the whole file down to actual values:

Spreadsheet         ← the whole file
  └─ Sheet          ← one tab
       └─ Range     ← a rectangle of cells
            └─ Values   ← a 2D array of actual data

A 2D array is an array whose entries are themselves arrays — rows of rows. Each outer entry is a row from the sheet; each inner entry is a cell value in that row. Reading values[1][2] means “row index 1, column index 2.”

In code:

const spreadsheet = SpreadsheetApp.getActiveSpreadsheet();  // Spreadsheet
const sheet = spreadsheet.getSheetByName("Orders");          // Sheet
const range = sheet.getRange("A1:C10");                      // Range
const values = range.getValues();                            // 2D array

Only the last line returns normal JavaScript data. Everything before it returns what’s usually called a handle object — a thing that represents part of the document but doesn’t contain the data itself.

What a handle object looks like up close

A handle object is closer to a TV remote than to a JSON blob. (A JSON blob is a chunk of data shaped as plain keys-and-values text — the format apps usually pass data around in. A handle object isn’t that; it’s an object with methods you call to ask for data.) Printing the handle isn’t useful:

Logger.log(spreadsheet);
// logs: Spreadsheet

No keys, no rows, no values — just the word Spreadsheet. The object doesn’t hold the spreadsheet data. It holds a reference to it, plus a set of methods (the “remote buttons”) for asking Google to fetch specific pieces.

The reason: Apps Script is talking to Google’s servers across a network boundary. Loading the entire spreadsheet up front would be huge and slow. Instead, the script holds a handle and only fetches what it asks for, one method call at a time.

The same shape, other Google products

The Sheets hierarchy isn’t a one-off. Every Google product exposes its own nested structure the same way.

Each step has its own methods that move further down. Document exposes .getBody(). Body exposes .getParagraphs(). Paragraph exposes .getText(). The naming changes per product, but the walk-the-hierarchy pattern is identical.

The Sheets walk, narrated

const ss = SpreadsheetApp.getActiveSpreadsheet();
// Now holding: the whole file. Can ask it for tabs, name, URL.

const sheet = ss.getSheetByName("Orders");
// Narrowed to: one tab. Can ask it for ranges, row count, charts.

const range = sheet.getRange("A1:C10");
// Narrowed to: a 10×3 rectangle. Can ask it for values, formulas, background colors.

const values = range.getValues();
// Finally normal data:
// [
//   ["Name",  "Item",     "Price"],
//   ["Alice", "Lemonade", 3],
//   ...
// ]

Writing back up the chain

Reading walks down. Writing goes the opposite direction — the developer holds a handle to a specific spot, then calls a setter on it:

const range = sheet.getRange("A1");   // handle to one cell
range.setValue("Updated");             // tell Google to write this value

const cell = sheet.getRange("B2");
cell.setBackground("#ffeecc");         // tell Google to recolor it

Same handle object, different methods. .getValue() reads; .setValue() writes. The walk down the hierarchy is how the script finds the right spot to read or write.