Dataloupe

dataloupe

CSV、JSON、NDJSON、Parquet、Excel ファイルを、1 つのコマンドで、自己完結型かつ完全オフラインのインタラクティブな HTML エクスプローラーに変換します。

npx dataloupe data.csv --open

AI エージェントが構築・保守しています（Aurelio Nakamura）。人間からの Issue、アイデア、PR を歓迎します。

▶ ブラウザーで試す — お手持ちの CSV／JSON／Parquet／Excel ファイルをドロップすると、すぐにエクスプローラーが表示されます。すべてクライアント側で動作するため、データがタブの外に出ることはありません（CLI と同じエンジンを使用）。

_{生成された HTML からライブキャプチャー：検索、並べ替え、仮想化テーブルのスクロール、テーマ切り替え — ネットワークリクエストは一切ありません。}

dataloupe はデータファイルを読み込み、その隣に単一の .html ファイルを書き出します。ダブルクリックして開いたり、メールで送ったり、Slack にドロップしたり、リポジトリにコミットしたりできます。並べ替え／検索／フィルター機能付きのテーブル、列ごとの統計、自動生成されるグラフに加え、ファイル内で完全に実行される組み込み SQL コンソールを備えています。また、ネットワークリクエストは一切行いません。CDN、Web フォント、テレメトリーはありません。データがマシンの外に出ることはありません。

これは単なる約束ではありません。生成されるすべてのファイルには、厳格な Content-Security-Policy メタタグ （default-src 'none'; connect-src 'none'; …）が含まれ、ページがネットワークリクエストを行おうとしても、ブラウザー自体がブロックします。ネットワークから隔離されたマシンで開いても、同じように動作します。

---

その理由

「CSV から HTML へ」変換するツールの多くは、ファイルをサーバーにアップロードするウェブサイトです。金融、医療、社内データなど、機密データを扱う場合には論外です。優れたローカル向けの代替ツールは、用途に対して高機能すぎます。

	データがマシンの外に出る	サーバーの起動が必要	単一ファイルで共有可能	Parquet と Excel を読み込み
オンライン CSV→HTML コンバーター	はい ❌	いいえ	場合による	まれ
Datasette	いいえ	はい	いいえ	プラグイン経由
VisiData（TUI）	いいえ	いいえ	いいえ	はい
dataloupe	いいえ ✅	いいえ ✅	はい ✅	はい ✅

dataloupe は、誰にでも渡せるポータブルな HTML ファイルを 1 つ生成します。相手側で何もインストールする必要はなく、オフラインでいつまでも使えます。

インストール

npx で実行できます。インストールは不要です。

npx dataloupe sales.csv

または、グローバルにインストールします。

npm install -g dataloupe
dataloupe sales.csv

Node.js ≥ 18 が必要です。このパッケージはビルド済みの自己完結型 CLIで、コンパイル手順も、取得が必要な実行時依存関係もありません。

レジストリではなくリポジトリに固定したい場合は、npx github:aurelio-nakamura/dataloupe sales.csv も使用できます。

使用方法

dataloupe <file> [options]

ARGUMENTS
  <file>                CSV, TSV, JSON, NDJSON/JSONL, Parquet, or Excel (.xlsx)
                        Use "-" or pipe to read from stdin (text formats only)

OPTIONS
  -o, --output <file>   output HTML path (default: <input>.html, or dataloupe.html for stdin)
      --open            open the result in your browser when done
      --limit <n>       load at most n rows (default: all)
      --format <fmt>    force format: csv|tsv|json|ndjson|parquet|xlsx
      --delimiter <d>   field delimiter for csv/tsv (default: auto)
      --sheet <name>    worksheet to read from an .xlsx file (default: first)
      --title <text>    human title shown in the header + browser tab
      --note <text>     provenance note shown under the header (why this export
                        exists, what upstream transform produced it, etc.)
  -h, --help            show this help
  -v, --version         print version

例：

npx dataloupe events.ndjson --open
npx dataloupe metrics.parquet -o report.html
npx dataloupe budget.xlsx --sheet Q3 --open
npx dataloupe big.csv --limit 100000
npx dataloupe q1.csv --title "Q1 Expenses" --note "Exported from ledger; nulls dropped, USD"

生成されたファイルには、確認可能な来歴情報（ソースファイル名、形式、生成日時、dataloupe のバージョン、行数、各列の推定型と統計情報）がすでに埋め込まれているため、受け取った人は常に、見ているものが「何」なのかを確認できます。また、レポートがどのように作成されたかも記録されます。ソースデータの **SHA-256（バイトサイズ付き）**と、適用された操作の順序（読み込み → フィルター → グループ化 → 並べ替え → 件数制限）が含まれているため、レポートが期待どおりの正確なバイト列から作成されたことを誰でも検証し、再現できます。これは特に、レポートを生成したクエリが自動的に記録される MCP の visualize_data ツールで役立ちます。 --title と --note を使うと、生成する人が人間向けの補足情報（エクスポートの目的や、上流でどのような変換が行われたか）をヘッダーに直接記載できます。

ビューアーで ⓘ about をクリックすると、折りたたみ可能な来歴パネルが開き、これらすべてのメタデータに加えて、現在適用されているフィルター、並べ替え、列の表示状態を平易な英語でリアルタイムに表示します。また、このビューへのリンクをコピーボタンもあるため、受け取った人は表示中のビューをブックマークしたり、共有したりできます。表示されるすべてのフィールドはファイル内に保存されており、外部から取得されることはありません。

また、標準入力も読み込めるため、シェルのパイプラインにそのまま組み込めます（形式は自動検出されます。--format で指定することもできます）。

psql -c "copy (select * from orders) to stdout csv header" | npx dataloupe - --open
cat data.csv | npx dataloupe -o report.html
curl -s https://api.example.com/items | npx dataloupe --format json --open

diff — データファイル用の git-diff

CSV に対する git diff はノイズだらけになります。行の並べ替え、引用符の付け直し、実際の変更がすべて同じように見えるからです。dataloupe diff はキーで行を照合し、実際に変更された内容を、自己完結型のオフライン HTML レポートとして表示します。

▶ ライブの差分レポートを見る — 実際の dataloupe diff の出力です（追加／削除／変更された行を、セル単位の old → new ハイライト付きで表示）。完全なオフライン環境でレンダリングされます。

npx github:aurelio-nakamura/dataloupe diff old.csv new.csv --key id --open

+3 added · −1 removed · ~5 changed · =1042 unchanged

• 追加／削除／変更された行を色分けし、変更された正確なセルを old → new として表示します。
• キーによる照合（--key id または --key region,date）により、行の並べ替えや引用符の付け直しは変更として扱われません。--key を省略すると、dataloupe は一意な ID のような列を自動検出し、該当する列がなければ行全体で照合します。
• あらゆる対応形式の組み合わせで動作します。.csv のエクスポートと .parquet のスナップショット、または先週の .xlsx と今週のファイルを比較できます。
• プライバシー保護も同じです。ネットワークリクエストはゼロで、データがマシンの外に出ることはありません。レポートをコミットしたり、メールで送ったり、レビューに添付したりできます。

CI の diff — プルリクエストでデータの変更をレビューする

GitHub Action を使うと、レビュアーは PR 内でデータファイルの「実際の変更」を確認できます。ダウンロード可能な自己完結型 HTML レポートと、ジョブ内の件数サマリーとして表示されます。データがランナーの外に出ることはありません。

# .github/workflows/data-diff.yml
on:
  pull_request:
    paths: ["data/**.csv"]
jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: git show "${{ github.event.pull_request.base.sha }}:data/people.csv" > base.csv || : > base.csv
      - uses: aurelio-nakamura/[email protected]
        id: diff
        with:
          before: base.csv
          after: data/people.csv
          key: id
          output: people-diff.html
      - uses: actions/upload-artifact@v4
        with: { name: data-diff, path: "${{ steps.diff.outputs.html }}" }

このステップは added／removed／changed／unchanged／changed-any の出力を公開するため（たとえば、データが変更されたときにチェックを失敗させることができます）、ジョブに Markdown のサマリーを書き込みます。すぐにコピーして使えるワークフローは examples/workflows/data-diff.yml にあります。

プログラム API

dataloupe はライブラリとしても利用できます。インストールして（npm install dataloupe）、独自のコードから同じ自己完結型の完全オフライン対応 HTML を生成できます。ビルドパイプライン、クエリ結果、生成データなどに便利です。TypeScript の型定義が含まれており、ESM 形式です。

import { renderRows, renderFile, datasetFromRows, renderHtml } from "dataloupe";
import { writeFileSync } from "node:fs";

// From in-memory rows (array of plain objects):
const html = renderRows(
  [
    { name: "Ada", born: 1815, field: "math" },
    { name: "Alan", born: 1912, field: "cs" },
  ],
  { source: "pioneers" },
);
writeFileSync("report.html", html);

// From a file (CSV/TSV/JSON/NDJSON/Parquet/XLSX):
writeFileSync("data.html", await renderFile("data.csv"));

// Or build the dataset (schema + stats) and render separately:
const ds = datasetFromRows(rows);
console.log(ds.columns, ds.types, ds.stats); // inspect
const out = renderHtml(ds);

エクスポート	説明
renderRows(rows, meta?)	メモリ上の行データ → 自己完結型 HTML 文字列。
renderFile(path, opts?)	ファイルを読み込む → 自己完結型 HTML 文字列。
renderText(text, format, opts?)	テキスト（csv/tsv/json/ndjson） → 自己完結型 HTML 文字列。
buildDataset(path, opts?)	ファイルを読み込む → 分析済み Dataset（スキーマ + 統計情報）。
datasetFromRows(rows, meta?)	メモリ上の行データ → 分析済み Dataset。
buildDatasetFromText(text, format, opts?)	テキスト文字列 → 分析済み Dataset。
renderHtml(dataset)	Dataset → 自己完結型 HTML 文字列。
diffFiles(before, after, opts?)	2 つのファイルを比較 → 自己完結型 HTML 差分レポート。
diffDatasets(before, after, opts?)	2 つの Dataset → 構造化された DiffResult。
renderDiffHtml(result)	DiffResult → 自己完結型 HTML 差分レポート。
VERSION	dataloupe のバージョン文字列。

<dataloupe-table> — エクスプローラーをあらゆる Web ページに埋め込む

スタンドアロンファイルではなく、独自のページ内でインタラクティブなエクスプローラーを使いたいですか？ <dataloupe-table> Web コンポーネントを追加するだけです。フレームワークも、ビルド手順も、サーバーも不要です。同じレンダリングエンジンをそのまま再利用し、サンドボックス化された <iframe>（一意の不透明なオリジン + 埋め込みの default-src 'none' CSP）内にマウントするため、指定したデータがブラウザーの外に出ることはなく、ホストページにアクセスすることもできません。

▶ ライブデモ

CDN から直接読み込めます。npm、ビルド、バンドラーは不要です。バンドルは約 110 KB で、実行時依存関係はゼロです。また、バージョン管理された git タグから配信されます。

<script type="module"
  src="https://cdn.jsdelivr.net/gh/aurelio-nakamura/[email protected]/dist/dataloupe-element.js"></script>


<dataloupe-table src="sales.csv" height="600"></dataloupe-table>

セルフホストを希望しますか？ 同じファイルを GitHub Pages から利用できます： https://aurelio-nakamura.github.io/dataloupe/embed/dataloupe-element.js

// Imperative: hand it in-memory rows
const el = document.querySelector("dataloupe-table");
el.rows = [{ name: "Ada", born: 1815 }, { name: "Alan", born: 1912 }];
// ...or raw text: el.setText(csvString, "csv");

属性：src、format、limit、title、height。イベント：dataloupe:load / dataloupe:error。バンドラーから登録するには、import "dataloupe/element" を使うこともできます。

MCP サーバー — AI アシスタントがローカルデータを探索できるようにします（オフライン）

dataloupe にはMCPサーバーが搭載されているため、Claude Desktop、 Cursor、VS Code などの MCP クライアントから、データベースも、実行中のサーバーも、 データのアップロードも必要なく、ローカルのデータファイルを直接調査してクエリを実行できます。 dataloupe の「データがマシンの外に出ることはない」という仕組みが、AI エージェントにも 適用されるようになりました。

他のデータ用 MCP サーバーとの違いは、特筆すべきツール visualize_data が、ファイルまたはクエリ結果を、ディスク上に保存される単一の、 完全オフラインで動作するインタラクティブな HTML エクスプローラーに変換し、そのパスを返すことです。 チャットに省略されたテキスト表を貼り付ける代わりに、エージェントはブラウザーで開ける、 共有可能な実際の成果物を作成できます（外部へのリクエストは一切なく、CSP によって強制されます）。

MCP クライアントに追加します（Claude Desktop／Cursor の mcpServers 設定例）：

{
  "mcpServers": {
    "dataloupe": {
      "command": "npx",
      "args": ["-y", "dataloupe", "mcp"],
      "env": { "DATALOUPE_MCP_ROOT": "/path/to/your/data" }
    }
  }
}

DATALOUPE_MCP_ROOT は省略可能ですが、設定を推奨します。このディレクトリ内にすべてのファイルアクセスを 制限します（シンボリックリンクによる回避にも安全です。チェック前にパスが正規化されます）。 省略可能な安全設定がほかに 2 つあります。

• DATALOUPE_MCP_MAX_BYTES — ファイルごとの読み取り上限（バイト単位、デフォルトは512 MiB）。このサイズを 超えるファイルは読み込む前に拒否されるため、1 回のリクエストでメモリを使い果たすことはありません。 無効にするには 0 を設定します。
• DATALOUPE_MCP_READONLY — 1／true に設定すると、サーバーは呼び出し元が指定した out_path への成果物の 書き込みを拒否します（任意のファイルを上書きする可能性があるためです）。 visualize_data／diff_data は引き続き成果物を返しますが、新規作成された一時ファイルにのみ保存します。

公開されるツール：

ツール	機能
list_data_files	ディレクトリ内の CSV／TSV／JSON／NDJSON／Parquet／Excel ファイルを一覧表示します
describe_data	スキーマ、行数／列数、列ごとの統計情報（型、null、ユニーク値、最小値／最大値／平均値／中央値、上位の値）を表示します
preview_data	先頭 N 行を Markdown テーブルで表示します
query_data	読み取り専用の構造化クエリ：where／select／order_by／limit／group_by ＋ count/sum/avg/min/max 集計
sql_query	ファイルに対する読み取り専用の SQL SELECT（WHERE／GROUP BY／ORDER BY／LIMIT ＋集計）。安全なプランにコンパイルされ、eval も書き込みもありません。LLM は構造化フィルターより SQL を自然に出力するため便利です
visualize_data	自己完結型でオフライン動作するインタラクティブな HTML エクスプローラーを（クエリ結果を対象にすることも可能）作成し、そのパスを返します
diff_data	2 つのファイルの git 形式の差分（追加／削除／変更された件数と、オプションのオフライン HTML レポート）

すべてのツールはデータに対して読み取り専用です。dataloupe がファイルを変更することはありません。

コンテナーとして実行する（Node/npm は不要）

dataloupe の MCP サーバーは公式 MCP Registry に io.github.aurelio-nakamura/dataloupe として公開され、GitHub Container Registry の OCI イメージとして配布されています。任意の MCP クライアントからイメージを指定してください（stdio 経由で JSON-RPC を使用します）。

{
  "mcpServers": {
    "dataloupe": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--mount", "type=bind,src=/path/to/your/data,dst=/data",
               "ghcr.io/aurelio-nakamura/dataloupe:latest"]
    }
  }
}

すべてオフラインで完結します。このイメージには実行時依存関係がなく、マウントした /data ディレクトリのみを読み取ります。

特長

• 完全にオフラインで出力。 生成される HTML にはすべてがインラインで埋め込まれます。<script src> も<link href> も、フォントも、fetch もありません。ご自身で確認してみてください。ネットワークを切断して、ファイルを開くだけです。
• 一般的な形式に幅広く対応。 CSV、TSV、JSON（オブジェクトの配列）、NDJSON/JSONL、Parquet、Excel (.xlsx) に対応。すべてネイティブ依存なしの純粋な JavaScript リーダーで処理します。Excel の日付セルは自動認識され、--sheet で複数シートのブックにも対応します。
• スキーマと型を自動推定。 整数、数値、ブール値、日付／日時、文字列に対応します。
• 列ごとの統計情報。 NULL 数、ユニーク値の数、数値の最小値／最大値／平均値／中央値／標準偏差、カテゴリ値の上位項目を表示します。
• グラフを自動生成。 数値列と日付列にはヒストグラム、カテゴリ列には頻度を示す棒グラフを表示します。小さなインライン SVG として描画されます。
• 高速で、並べ替えと絞り込みが可能なテーブル。 全列を対象にした全文検索と、大きなファイルでもスムーズに動作する仮想化されたボディを備えています。
• SQL コンソールを内蔵。 ビューアーで ▸_ SQL を押すと、データに対して実際の SELECT クエリを実行できます。WHERE、AND、LIKE、IN、GROUP BY、集計（COUNT／SUM／AVG／MIN／MAX）、ORDER BY、LIMIT／OFFSET に対応しています。共有可能なファイル内で、ブラウザーだけで完全に実行されます。サーバーも WASM のダウンロードもネットワークも不要です。他の単一ファイル出力にはない機能です。
• ビューを共有可能。 現在の検索条件、並べ替え、フォーカス中の列、テーマは URL ハッシュに保存されるため、絞り込みや並べ替えを適用したビューをブックマークして共有できます。アドレスバーの URL をコピーすれば（ダブルクリックで開いた file://…#… のファイルでも動作します）、同じファイルを開いた相手にもまったく同じビューが表示されます。引き続き完全にオフラインで、ハッシュによってリクエストが発生することはありません。
• データの出所を示すパネル。 ⓘ about パネルには、埋め込み元データ／形式／タイムスタンプ／バージョン／形状と、人が付けたタイトルやメモが表示されます。さらに、現在の絞り込み／並べ替え／列ビューの説明も平易な言葉で表示され、ワンクリックで このビューへのリンクをコピーできます。すべてファイル内に含まれています。
• diff モード — データファイル用の git diff です。キーで照合した追加／削除／変更行をセル単位でold → newのハイライト付きで表示し、オフラインで使える HTML レポートとして出力します。
• ライトテーマとダークテーマ、レスポンシブレイアウト、キーボード操作に対応しています。
• 小容量。 一般的なレポートは、データを除けば数十 KB です。

仕組み

dataloupe は Node でファイルを解析し、スキーマを推定して列ごとの統計情報を計算し、その結果を、手書きの小さなバニラ JavaScript 製ビューアー（ビルド時にバンドルしてインライン化）とともに単一の HTML ドキュメントにシリアライズします。出力にはランタイム依存がなく、ページを開くときにコードが取得されることもありません。

開発

git clone https://github.com/aurelio-nakamura/dataloupe
cd dataloupe
npm install
npm run build      # builds the inlined viewer + CLI into dist/
npm test           # vitest
node dist/cli.js path/to/data.csv --open

貢献

バグ報告、機能リクエスト、プルリクエストを歓迎します。dataloupe によってファイルが壊れたり、型が誤って読み取られたりした場合は、匿名化したサンプルを issue に添付するのが、最も早く修正につながります。

ビルドとテストの手順、コードの構成、入力形式の追加方法については、CONTRIBUTING.md をご覧ください。

ライセンス

MIT © Aurelio Nakamura