ピボットテーブルプラグイン

このテキストは第三者が書いたもので、自動翻訳されています。英語の原文を読む

Beekeeper Studio のあらゆるクエリ結果、グリッドの選択範囲、テーブルをピボットテーブルに変換し、Excel ブック、PDF、画像、Markdown、CSV、HTML、JSON として共有できます。

ピボットテーブルの作成：フィールドを行・列・値にドラッグし、日付を年でグループ化、小計・ヒートマップ・フィルターを追加してからエクスポート

_{プラグインの開発用ハーネスで 5,000 件のサンプル注文を使って録画しました。少し早送りしています。}

機能一覧


ドラッグ＆ドロップ	スプレッドシートのピボットテーブルと同様の行、列、値、フィルター
11種類の集計	個数、ユニーク数、合計、平均、最小、最大、中央値、標準偏差、分散、最初、最後
合計に対する %	任意の値を総計、行合計、列合計に対する割合で表示
日付のグループ化	年、四半期、月、週、日、時、月（年内）、曜日
フィルターと並べ替え	検索と件数表示で値を選択、A→Z、Z→A、または値で並べ替え
レイアウト	合計、小計、値の列／行配置、小数点以下桁数の固定、ヒートマップ
8種類のエクスポート形式	Excel、Excel + 元データ、PDF、PNG、Markdown、CSV、HTML、JSON
3通りのコピー	スプレッドシートのセル、Markdown テーブル、画像
あらゆるデータソース	グリッドの選択範囲、クエリ、テーブル（タブのフィルター付き）、最大 100,000 行
アプリに馴染む	ライト／ダークテーマに追従し、タブごとにレイアウトを保存、ネットワーク通信なしでローカル実行

ピボットの作成

データのすべての列がフィールドリストに表示されます。フィールドをゾーンにドラッグするか、クリックして配置先を選択します:

行と列はデータをグループ化します。複数のフィールドを重ねるとグループをネストでき、チップをドラッグして並べ替えられます。入れ替えで行と列を反転します。
値はセル内の数値です。同じフィールドを複数回追加して、たとえば合計と平均を並べて表示できます。値がない場合は行数をカウントします。
フィルターは行や列を追加せずにデータを絞り込みます。

チップをフィールドリストにドラッグして戻すと削除されます。チップをクリックするとオプションが表示されます。

新しいピボットは推奨レイアウトから始まります:

行: status、plan、country などのカテゴリ的な列。
列: メインの日付列。データの範囲に合わせて日、月、四半期、年でグループ化されます。カテゴリ列がない場合は行に配置されます。
値: total、amount、quantity などの金額的な列の合計。該当する列がない場合は行数。

ID、ほぼ空の列、自由テキスト、updated_at などのタイムスタンプは使用されません。オプションのレイアウトをリセットで推奨レイアウトに戻せます。

値の集計

値のチップをクリックして表示内容を変更します:

集計方法	対象
個数、ユニーク数	任意の列、またはフィールド未選択時は行
合計、平均、中央値、標準偏差、分散	数値（数値形式のテキストを含む）
最小、最大	数値、日付、テキスト
最初、最後	任意の列

表示形式で、値を総計、行合計、列合計に対する割合に変換できます。

グループ化、フィルター、並べ替え

行、列、フィルターのチップをクリックすると次の操作ができます:

日付のグループ化: 年、四半期、月、ISO 週、日、時、月（年内）、曜日。日付はデータベースに書かれたままグループ化されるため、タイムゾーンによってずれることはありません。
表示する値: 各値と行数のチェックリスト、検索ボックス、すべて／なし、単一の値だけを残す「のみ」。フィルター中のチップはハイライトされます。
並べ替え: ラベルを A→Z または Z→A（数値は数値順、null は最後）、または最初の値の大きい順・小さい順。

レイアウトオプション

サイドバーのオプションから:

総計用の合計列と合計行、行や列がネストされている場合のグループごとの小計。
値の配置: 複数の値を持つピボットで、値を列または行に配置。
小数点以下: 自動（整数は整数のまま、その他の値は2桁、割合は1桁）または 0〜4 桁の固定。
ヒートマップは各値を最小から最大まで色の濃淡で表示します。

上部のタイトルはタブ名になり、エクスポートにも表示されます。

エクスポートでファイルを保存します。非常に大きなピボットで画面上のグリッドが先頭の行しか表示していなくても、エクスポートには常にピボット全体が含まれます。

形式	内容
Excel	結合されたヘッダー、数値・割合の書式、太字の合計、固定されたヘッダー行とラベル列
Excel + 元データ	同じブックに読み込んだ行の2枚目のシートを追加。Excel で再ピボットできます
PDF	幅が広い場合は横向き。可能な限り縮小して収め、非常に幅の広いピボットは行ラベルを繰り返すページに分割します
画像	タイトル、ソース、フィルター付きの鮮明な PNG。スライド、ドキュメント、チャットにそのまま使えます
Markdown	README、Issue、Wiki 向けの GitHub 形式のテーブル
CSV	ヘッダー行1行と生の数値。行ラベルは各行に繰り返されます
HTML	結合ヘッダーを保持したスタイル付きの単独ページ
JSON	列ヘッダーをキーとする、1行につき1オブジェクト

コピーでピボットをクリップボードに、スプレッドシートのセル（割合も含めて Excel や Google Sheets に貼り付け可能）、Markdown テーブル、または画像としてコピーします。

デモのピボットに対して画像エクスポートが出力する PNG です:

タイトル、ソース、フィルター概要付きの売上ピボットの画像エクスポート

ピボットテーブルを開く

場所	メニュー項目	使用するデータ
新規タブのドロップダウン（`+` の隣）、ツールメニュー	Pivot Table	プラグイン内で選択したクエリまたはテーブル
クエリ結果またはテーブルデータ: セルまたは左上の角を右クリック	Pivot Table from Selection	選択したセル
クエリタブのヘッダー、またはクエリエディタの右クリックメニュー	Pivot Query Results	行数制限付きで再実行したクエリ
サイドバーのテーブル、またはテーブルタブのヘッダー	Open in Pivot Table	タブのフィルターを `WHERE` 句として適用したテーブル

グリッドの結果セット全体をピボットするには、まずすべてのセルを選択し（グリッド左上の角をクリックするか Ctrl/Cmd+A を押す）、右クリックします。

データソースはサイドバーの鉛筆ボタンからいつでも変更でき、SQL クエリまたはテーブル（WHERE 句は任意）を指定できます。ステータスバーの SQL でデータを読み込んだ正確なクエリを確認できます。

行数制限

ピボットはプラグイン内で計算されるため、データは行数制限付きで読み込まれます。デフォルトは 10,000 行で、最大 100,000 行まで設定できます（選択内容は記憶されます）。

クエリは SELECT * FROM (<query>) AS pivot_source LIMIT n でラップされ（SQL Server では TOP、Oracle では ROWNUM、Firebird では FIRST）、制限はデータベース側で行われます。
データベースがラップしたクエリを拒否した場合（例: SQL Server の CTE）、クエリをそのまま実行して先頭の行を残すかを確認するプロンプトが表示されます。データを変更する可能性のあるステートメントが確認なしに再実行されることはありません。
SQL サブクエリに対応していないデータベース（MongoDB、Redis、Cassandra など）では、クエリをそのまま実行して先頭の行を残します。
制限に達した場合はバナーが表示されます。合計は読み込まれた行のみが対象です。
保存したタブを再度開いた場合、クエリソースは自動実行されず、クエリを実行のクリックを待ちます。選択範囲とテーブルはすぐに読み込まれます。

ライトテーマとダークテーマ

プラグインは Beekeeper Studio のテーマカラーを使用し、アプリに合わせて切り替わります。

ライト	ダーク

インストール

公開後は、Beekeeper Studio（5.5 以降）のツール → プラグインの管理から Pivot Tables をインストールできます。

ビルドを手動でインストールするには、リリースから bk-plugin-pivot-tables-<version>.zip をダウンロードし、Beekeeper Studio のプラグインディレクトリに展開します:

Linux: ~/.config/beekeeper-studio/plugins/bk-plugin-pivot-tables
macOS: ~/Library/Application Support/beekeeper-studio/plugins/bk-plugin-pivot-tables
Windows: %APPDATA%\beekeeper-studio\plugins\bk-plugin-pivot-tables

開発

yarn install
yarn dev        # links the project into Beekeeper's plugins directory and serves it with hot reload
yarn harness    # runs the plugin in a browser against a fake Beekeeper Studio
yarn test:run   # unit tests (Vitest)
yarn typecheck
yarn build      # production build into dist/
yarn package    # release zip in release/ (after yarn build)

yarn dev は @beekeeperstudio/vite-plugin を使用し、プロジェクトをプラグインディレクトリにシンボリックリンクします。Beekeeper Studio でプラグインを有効にし、上記のいずれかのメニューからピボットを開いてください。

yarn harness は dev/host.html を http://localhost:5199/dev/host.html で配信します。プラグインを iframe でホストし、5,000 件のサンプル注文を持つインメモリ SQLite データベースから API リクエストに応答するため、Beekeeper Studio なしで UI やエクスポートを開発できます。クエリパラメータ:

command=new-pivot|pivot-selection|pivot-query|pivot-table はエミュレートするメニュー項目を選択します。
theme=light|dark はテーマを設定します。
fresh=1 は保存されたタブの状態をクリアします。
prod=1 は dist/ から本番ビルドを読み込みます（先に yarn build を実行してください）。

docs/demo.gif は scripts/record-demo.cjs によってハーネスから録画されるため、UI 変更後に再録画できます。yarn harness を実行した状態で:

npm install -g playwright && npx playwright install chromium   # once; also needs ffmpeg
NODE_PATH="$(npm root -g)" node scripts/record-demo.cjs

プロジェクト構成

manifest.json            Plugin manifest: one view, menu entries for each way of opening it
src/App.vue              Startup, data loading, state persistence, export actions
src/components/          Field list, drop zones, menus, pivot table renderer, source editor
src/lib/pivot/           Pivot engine, aggregators, date grouping, grid layout (headers and spans)
src/lib/source/          Loading data: selections, queries and tables with dialect-aware row limits
src/lib/export/          Excel, PDF, image, Markdown, CSV, HTML and JSON exporters
tests/                   Vitest specs
dev/                     Browser harness that emulates Beekeeper Studio

ピボットエンジンは行・列のスパンを持つセルのグリッドを生成します（src/lib/pivot/grid.ts）。画面上のテーブルとすべてのエクスポーターはこのグリッドから描画されるため、すべて同じレイアウトになります。

リリース

bin/make-release.sh を実行します。既存のタグから次のバージョンを提案し、manifest.json と package.json の version を設定してコミットし、v1.0.0 のような対応するタグをプッシュします。
リリースワークフローがテストとビルドを行い、manifest.json と bk-plugin-pivot-tables-<version>.zip を含む GitHub リリースのドラフトを作成します。内容を確認して公開してください。
プラグインマネージャーに掲載するには、beekeeper-studio-plugins の plugins.json にエントリを追加します。

制限事項

テーブルタブのフィルターは、serializeTab のフィルター変更を含む Beekeeper Studio のビルドでのみプラグインに渡されます。古いバージョンではテーブル全体が（行数制限付きで）開かれますが、ソースエディタで WHERE 句を入力することはできます。
非常に大きなピボットでは、グリッドに先頭の 500 行と 300 列が表示されます（「さらに表示」で行を追加読み込み）。エクスポートには常にすべてが含まれます。
画像には先頭の 2,000 行が含まれます。
埋め込みの DejaVu フォントが対応していないため、PDF エクスポートでは CJK 文字を描画できません。

ライセンス

GPL-3.0。PDF エクスポート用に DejaVu フォント（Bitstream Vera ライセンス）を同梱しています。

Pivot Tables

Readme