大量データの一括高速投入 — setRangeData / setRangeFormulas

level: intermediate / verified: 2026-10-17 / 5言語タブ対応 / 目次へ / English

やりたいこと

何千・何万セルもの値や数式を、セルごとに getCells() するのではなく 2次元配列にまとめて一度に高速投入する。CSV やデータベースの検索結果などの行列表を、最速かつ最小のメモリでワークシートに一括反映します。

やり方使うもの特徴
セルごとに投入ws.getCells(r, c).setNumberValue(...)少量セル向け。呼び出し回数に比例してオーバーヘッドが増加します。
2次元配列で値投入(最高速・推奨)ws.setRangeData(startA1, data)最速・推奨。 行列データを素の配列で一括転送。数値文字列は自動的に数値セルとして保存。
2次元配列で数式投入(最高速・推奨)ws.setRangeFormulas(startA1, formulas)最速・推奨。 計算列の数式群を 2次元配列で一度に流し込む(先頭の "=" は不要)。

対象クラス

WorkSheet

メソッド説明
setRangeData(startA1, data)左上開始セル(例: "A1")から、2次元配列(各行・各列の文字列)の値を一括高速入力します。
setRangeFormulas(startA1, formulas)左上開始セル(例: "D2")から、2次元配列(各行・各列の数式文字列、"="不要)を一括高速入力します。

コード

実行結果:

// bulk-input.js — 2次元配列による値と数式の一括高速投入 (nodeosbxl)
const { nodeosbxl } = require("nodeosbxl");

const app = new nodeosbxl.App();
const wb = app.createWorkBook("bulk-input.xlsx");
const ws = wb.openWorkSheet("Sheet1");

// ---------- 1. 2次元配列による値の一括高速投入 (setRangeData) ----------
// 各行・各列の値を文字列の2次元配列として用意し、左上セルを指定して一度に流し込みます。
// 数値形式の文字列 ("100" 等) は自動的に数値セルとして正しく認識・保存されます。
const data = [
    ["商品名", "単価", "数量", "金額"],
    ["りんご", "100", "3"],
    ["みかん", "50", "6"],
    ["ぶどう", "150", "2"],
];
ws.setRangeData("A1", data);

console.log("[1] setRangeData 投入後:");
for (const a1 of ["A1", "B2", "C2", "D1"]) {
    console.log(`    ${a1} = ${JSON.stringify(ws.getRange(a1).getValue()[a1])}`);
}

// ---------- 2. 2次元配列による数式の一括高速投入 (setRangeFormulas) ----------
// 計算列の数式群を2次元配列で一度に流し込みます(先頭の "=" は不要)。
// ヘッダー行(D1)を除いた D2 セルから数式を展開します。
const formulas = [
    ["B2*C2"],
    ["B3*C3"],
    ["B4*C4"],
];
ws.setRangeFormulas("D2", formulas);

console.log("[2] setRangeFormulas 投入後:");
console.log("    数式 D2:D4 =", JSON.stringify(ws.getRange("D2:D4").getFormula()));
console.log("    計算値 D2:D4 =", JSON.stringify(ws.getRange("D2:D4").getValue(true)));

// ---------- 3. 速度比較(2,000 行 x 5 列 = 10,000 セル)----------
const ROWS = 2000, COLS = 5;

// セルごとに getCells() して投入
const wsCell = wb.addWorkSheet("CellByCell");
let t = Date.now();
for (let r = 1; r <= ROWS; r++) {
    for (let c = 1; c <= COLS; c++) wsCell.getCells(r, c).setNumberValue(r * 100 + c);
}
const msCell = Date.now() - t;

// 2次元配列で setRangeData() 投入 (最高速)
const wsBulk = wb.addWorkSheet("Bulk");
t = Date.now();
const matrix = [];
for (let r = 1; r <= ROWS; r++) {
    const row = [];
    for (let c = 1; c <= COLS; c++) row.push(String(r * 100 + c));
    matrix.push(row);
}
const msBuild = Date.now() - t;
t = Date.now();
wsBulk.setRangeData("A1", matrix);
const msApply = Date.now() - t;

console.log(`[3] ${ROWS * COLS} セルの投入速度比較:`);
console.log(`    セルごと getCells().setNumberValue() : ${msCell} ms`);
console.log(`    setRangeData (構築${msBuild} + 投入${msApply}) : ${msBuild + msApply} ms (最速)`);

const a = wsCell.getRange("E2000:E2000").getValue(true)["E2000"];
const b = wsBulk.getRange("E2000:E2000").getValue(true)["E2000"];
console.log(`[検証] 両方式とも E2000 = ${a === Number(b) ? b : `不一致 ${a} / ${b}`}`);

wb.save();
wb.close();
[1] setRangeData 投入後:
    A1 = "商品名"
    B2 = 100
    C2 = 3
    D1 = "金額"
[2] setRangeFormulas 投入後:
    数式 D2:D4 = {"D2":"B2*C2","D3":"B3*C3","D4":"B4*C4"}
    計算値 D2:D4 = {"D2":300,"D3":300,"D4":300}
[3] 10000 セルの投入速度比較:
    セルごと getCells().setNumberValue() : 72 ms
    setRangeData (構築2 + 投入25) : 27 ms (最速)
[検証] 両方式とも E2000 = 200005

[3] の ms は実行環境によって変わります(上記は実機での 1 実行例)。

解説

速度とパフォーマンス

同一環境(Linux x86_64 / Intel Xeon / Python・PHP 実測負荷テスト)におけるセル投入速度の比較です。

規模(セル数)セルごと getCells().setNumberValue()setRangeData()(2次元配列一括投入)高速化倍率実務上のメリット
10,000 セル
2,000 行 x 5 列
約 72 〜 185 ms約 27 〜 95 ms
(配列構築含む)
約 2 〜 2.7 倍高速Web API の帳票ダウンロードが 0.1 秒未満で即座に完了。
100,000 セル
20,000 行 x 5 列
約 960 〜 1,300 ms約 280 〜 350 ms約 3 〜 4.7 倍高速10 万セルの巨大テーブルも 0.3 秒台で一括流し込み可能。
200,000 セル
50,000 行 x 4 列
約 2,200 〜 2,400 ms約 570 〜 630 ms約 3.5 〜 4.1 倍高速既存 OSS(PhpSpreadsheet / POI)が OOM(メモリ不足)で停止する規模でも低メモリで安全完走。

※ ファイル保存(.xlsx 出力)や数式再計算を含めた総合プラットフォーム(GCP C3/C4・macOS M4・Windows 11)の実測限界ベンチマーク結果は、3OS総合負荷テストレポート を参照してください。

setRangeData() は、言語側のブリッジ境界呼び出しオーバーヘッドを最小化し、C++ エンジン側で直接セル配置および SST(共有文字列テーブル)登録を並列・一括処理するため、セル数が増えるほど圧倒的な差が生まれます。

使いどころ

注意点

関連