getValues

function getValues<T = unknown>(
  target: GoogleAppsScript.Spreadsheet.Sheet | GoogleAppsScript.Spreadsheet.Range,
  config: GetValuesConfig | null | undefined = {}
): T[];

With headerRow set, each row arrives as an object keyed by the column names, which is what makes a filter readable: row.status instead of row[4]. Where a name repeats, the leftmost column wins.

filter narrows the rows, offset and limit page what is left, and mapper decides what each surviving row becomes. display reads the values as a person sees them — a formatted date as its text rather than as a Date — which is a different thing from what is stored, not a cosmetic switch.

A sheet reads its whole data range; a range reads only itself, which is one service call over a block instead of over everything. Positions stay one-based on the sheet, so a row keeps its real number and headerRow names a row of the sheet, not an offset into the range.

Parameters

Parameter	Type	Description
`target`	`GoogleAppsScript.Spreadsheet.Sheet \\| GoogleAppsScript.Spreadsheet.Range`	The sheet to read, or the range to read: only its cells are fetched.
`config` (optional) `= {}`	`GetValuesConfig \\| null \\| undefined`	`headerRow`, `display`, `filter`, `offset`, `limit` and `mapper`.

Returns

T[] — the rows that survived, in sheet order.

Throws

Exception	Condition
`InvalidSheetException`	the first argument is neither a sheet nor a range.

Examples

Reading rows

const sheet = SpreadsheetApp.getActiveSheet();

const active = getValues(sheet, {
  headerRow: 1,
  filter: (row) => row.status === "active",
  mapper: (row) => row.email,
  limit: 100
});

Reading one block

const sheet = SpreadsheetApp.getActiveSheet();

// Only A1:C50 is fetched; the header is row 1 of the sheet.
const rows = getValues(sheet.getRange("A1:C50"), { headerRow: 1 });

Source

src/appsscript/sheet/getValues.ts

23 September 2026

This documentation was generated with AI (Claude) from the library's source code.

apps-script-utils 2.1.1 Help