Skip to content

DataFrame and Google Sheets

BareFrame is the core DataFrame in gaslamp. It provides a pandas/polars-style API for working with tabular data in Google Apps Script.

This guide focuses on reading from and writing to Google Sheets — the most common use case in GAS workflows.

Reading from a Sheet

fromSheet

Reads the entire data range of a sheet. The first row is treated as column headers by default.

JavaScript
function example_fromSheet() {
  const sheet = SpreadsheetApp.getActiveSheet();
  const df = gaslamp.BareFrame.fromSheet(sheet);

  console.log(df.headers);  // ["name", "age", ...]
  console.log(df.length);   // number of data rows
}

To provide explicit column names (all rows become data rows):

JavaScript
const df = gaslamp.BareFrame.fromSheet(sheet, ["name", "age", "city"]);
// All rows are treated as data rows using the provided headers

If the sheet has title or metadata rows above the header row, use getDataRange().getValues() with slice() to skip them before passing to fromArrays:

JavaScript
// Sheet layout:
//   Row 1: "Sales Report Q1"    ← title row (skip)
//   Row 2: "name", "age", ...   ← header row
//   Row 3+: data rows

const values = sheet.getDataRange().getValues();
const df = gaslamp.BareFrame.fromArrays(values.slice(1));
// slice(1) removes the title row; row 2 becomes the header

fromRange

Reads a specific cell range instead of the full sheet. The first row is treated as column headers by default.

JavaScript
function example_fromRange() {
  const sheet = SpreadsheetApp.getActiveSheet();
  const range = sheet.getRange("A1:C10");
  const df = gaslamp.BareFrame.fromRange(range);

  console.log(df.headers);  // ["name", "age", "city"]
  console.log(df.length);   // 9 (row 1 is header)
}

To provide explicit column names (all rows become data rows):

JavaScript
const range = sheet.getRange("A1:C10");
const df = gaslamp.BareFrame.fromRange(range, ["name", "age", "city"]);
// All 10 rows are treated as data rows using the provided headers

Writing to a Sheet

toSheet — overwrite

By default, toSheet clears the sheet and writes from row 1 with a header row.

JavaScript
function example_toSheet() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet()
    .getSheetByName("Output");

  const df = gaslamp.BareFrame.fromColumns({
    name: ["Alice", "Bob"],
    age:  [25, 30],
  });

  df.toSheet(sheet);
  // Sheet now contains:
  // name  | age
  // Alice | 25
  // Bob   | 30
}

toSheet — append

Pass { clear: false, header: false, startRow: ... } to append rows without erasing existing data.

JavaScript
function example_appendToSheet() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet()
    .getSheetByName("Log");

  const df = gaslamp.BareFrame.fromColumns({
    name: ["Carol"],
    age:  [28],
  });

  df.toSheet(sheet, {
    clear: false,
    header: false,
    startRow: sheet.getLastRow() + 1,
  });
  // New row appended below existing data
}

toSheet options

Option Type Default Description
clear boolean true Clear sheet contents before writing
header boolean true Write column names as the first row
startRow number 1 1-based row number to start writing

Transforming a DataFrame

Each operation has its own dedicated guide:

Practical Workflow

A complete example: read from one sheet, filter rows, and write results to another sheet.

JavaScript
function workflow_filterAndExport() {
  const book = SpreadsheetApp.getActiveSpreadsheet();

  // 1. Read
  const inputSheet = book.getSheetByName("Employees");
  const df = gaslamp.BareFrame.fromSheet(inputSheet);

  // 2. Transform
  const seniors = df.filter(
    (row) => row.get("age") >= 40
  );
  const result = seniors.select(["name", "department", "age"]);

  // 3. Write
  const outputSheet = book.getSheetByName("Seniors")
    ?? book.insertSheet("Seniors");
  result.toSheet(outputSheet);

  console.log(`Exported ${result.length} rows.`);
}

Next Steps