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행
자연스러운 통합	라이트/다크 테마를 따르고, 탭별 레이아웃을 저장하며, 네트워크 호출 없이 로컬에서 실행

피벗 만들기

데이터의 모든 열이 Fields 목록에 표시돼요. 필드를 영역으로 드래그하거나, 클릭해서 넣을 위치를 선택하세요:

• Rows와 Columns는 데이터를 그룹화해요. 여러 필드를 쌓아 그룹을 중첩하고, 칩을 드래그해 순서를 바꿀 수 있어요. Swap은 행과 열을 맞바꿔요.
• Values는 셀에 들어가는 숫자예요. 같은 필드를 여러 번 추가할 수 있어서, 예를 들어 합계와 평균을 나란히 보여줄 수 있어요. 값이 없으면 피벗은 행 개수를 세요.
• Filters는 행이나 열을 추가하지 않고 데이터 범위를 좁혀요.

칩을 필드 목록으로 다시 드래그하면 제거돼요. 칩을 클릭하면 옵션을 볼 수 있어요.

새 피벗은 추천 레이아웃으로 시작해요:

• Rows: status, plan, country 같은 범주형 열.
• Columns: 주요 날짜 열로, 데이터 범위에 맞춰 일, 월, 분기 또는 연 단위로 그룹화돼요. 범주형 열이 없으면 대신 Rows에 들어가요.
• Values: total, amount, quantity 같은 금액형 열의 합계, 또는 그런 열이 없으면 행 개수.

ID, 대부분 비어 있는 열, 자유 텍스트, updated_at 같은 타임스탬프는 사용되지 않아요. Options의 Reset layout을 누르면 추천 레이아웃으로 돌아가요.

값 요약하기

값 칩을 클릭해 표시 내용을 바꾸세요:

요약 방식	적용 대상
개수, 고유 개수	모든 열, 필드를 선택하지 않으면 행
합계, 평균, 중앙값, 표준편차, 분산	숫자(숫자 형태의 텍스트 포함)
최솟값, 최댓값	숫자, 날짜, 텍스트
첫 값, 마지막 값	모든 열

Show as는 값을 전체 합계, 행 합계 또는 열 합계 대비 백분율로 바꿔요.

그룹화, 필터링, 정렬

행, 열 또는 필터 칩을 클릭하면 다음을 설정할 수 있어요:

• Group dates by: 연, 분기, 월, ISO 주, 일, 시, 연중 월, 요일. 날짜는 데이터베이스에 기록된 그대로 그룹화되므로 시간대 때문에 밀리지 않아요.
• Show values: 모든 값과 행 개수를 담은 체크리스트, 검색창, All / None, 값 하나만 남기는 “only”. 필터가 적용된 칩은 강조 표시돼요.
• Sort: 레이블을 A→Z 또는 Z→A로(숫자는 숫자 순, null은 마지막), 또는 첫 번째 값의 크기 기준으로 큰 순이나 작은 순으로 정렬해요.

레이아웃 옵션

사이드바의 Options에서:

• 전체 합계를 위한 Totals column과 totals row, 행이나 열이 중첩된 경우 그룹별 subtotals.
• 값이 여러 개인 피벗에서 Values in으로 값을 열 또는 행에 배치.
• Decimals: 자동(정수는 정수 그대로, 다른 값은 소수 2자리, 백분율은 1자리) 또는 0~4자리 고정.
• Heatmap은 각 값을 최솟값부터 최댓값까지 색으로 음영 처리해요.

상단의 제목은 탭 이름이 되고 내보낸 파일에도 표시돼요.

내보내기와 공유

Export는 파일로 저장해요. 화면 그리드에 아주 큰 피벗의 앞부분 행만 보이더라도 내보낸 파일에는 항상 피벗 전체가 들어가요.

형식	결과물
Excel	병합된 헤더, 숫자 및 백분율 서식, 굵은 합계, 고정된 헤더 행과 레이블 열
Excel + 원본 데이터	같은 통합 문서에 로드된 행을 담은 두 번째 시트가 추가돼 Excel에서 바로 다시 피벗할 수 있어요
PDF	너비가 넓으면 가로 방향. 가능한 경우 크기를 줄여 맞추고, 아주 넓은 피벗은 행 레이블을 반복하는 여러 페이지로 나눠요
이미지	제목, 소스, 필터가 포함된 선명한 PNG로 슬라이드, 문서, 채팅에 바로 쓸 수 있어요
Markdown	README, 이슈, 위키용 GitHub 스타일 표
CSV	헤더 행 하나와 원시 숫자, 모든 행에 행 레이블 반복
HTML	병합된 헤더를 유지하는 독립형 스타일 페이지
JSON	행마다 열 헤더를 키로 하는 객체 하나

Copy는 피벗을 스프레드시트 셀(Excel이나 Google Sheets에 백분율까지 그대로 붙여넣기 가능), Markdown 표 또는 이미지로 클립보드에 복사해요.

데모의 피벗을 Image로 내보내면 이런 PNG가 만들어져요:

피벗 테이블 열기

위치	메뉴 항목	사용되는 데이터
새 탭 드롭다운(+ 옆), Tools 메뉴	Pivot Table	플러그인에서 선택한 쿼리 또는 테이블
쿼리 결과 상태 표시줄: Visualize	Pivot Table	선택한 셀 또는 결과의 모든 행
테이블 데이터 상태 표시줄: Visualize	Pivot Table	선택한 셀 또는 뷰의 필터를 WHERE 절로 적용한 테이블
쿼리 결과 또는 테이블 데이터: 셀이나 왼쪽 위 모서리를 우클릭	Pivot Table from Selection	선택한 셀
쿼리 탭 헤더 또는 쿼리 에디터의 우클릭 메뉴	Pivot Query Results	행 제한을 걸어 다시 실행한 쿼리
사이드바의 테이블 또는 테이블 탭 헤더	Open in Pivot Table	탭의 필터를 WHERE 절로 적용한 테이블

결과 전체를 피벗하려면 아무것도 선택하지 않은 상태에서 Visualize → Pivot Table을 사용하세요. 테이블 뷰에서는 그리드에 표시된 페이지만이 아니라 테이블 자체를 읽어요(행 제한까지, 기본값 10,000).

데이터 소스는 사이드바의 연필 버튼으로 언제든지 바꿀 수 있고, 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 등)는 쿼리를 작성된 그대로 실행하고 앞부분 행만 사용해요.
• 제한에 도달하면 배너가 표시돼요. 합계는 불러온 행만 대상으로 해요.
• 저장된 탭을 다시 열면 쿼리 소스는 자동으로 실행되지 않고 Run query를 클릭할 때까지 기다려요. 선택 영역과 테이블은 바로 불러와요.

라이트 및 다크 테마

플러그인은 Beekeeper Studio의 테마 색상을 사용하고 앱과 함께 전환돼요.

라이트	다크

설치

공개되면 Beekeeper Studio(5.5 이상)의 Tools → Manage Plugins에서 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|pivot-results는 에뮬레이션할 메뉴 항목을 선택해요.
• 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). 화면의 표와 모든 내보내기 기능이 이 그리드로 렌더링하므로 모두 같은 레이아웃을 보여줘요.

릴리스

1. bin/make-release.sh를 실행하세요. 기존 태그를 바탕으로 다음 버전을 제안하고, manifest.json과 package.json의 version을 설정한 뒤 커밋하고 v1.0.0 같은 대응 태그를 푸시해요.
2. 릴리스 워크플로가 테스트와 빌드를 거쳐 manifest.json과 bk-plugin-pivot-tables-<version>.zip이 포함된 초안 GitHub 릴리스를 만들어요. 검토한 뒤 게시하세요.
3. Plugin Manager 목록에 올리려면 beekeeper-studio-plugins의 plugins.json에 항목을 추가하세요.

제한 사항

• 테이블 탭 필터는 serializeTab 필터 변경이 포함된 Beekeeper Studio 빌드에서만 플러그인에 전달돼요. 이전 버전에서는 테이블 전체가 열리며(행 제한 적용), 소스 에디터에 WHERE 절을 직접 입력할 수는 있어요.
• 아주 큰 피벗의 경우 그리드에는 처음 500행과 300열만 표시돼요(“Show more”로 행을 더 불러올 수 있어요). 내보낸 파일에는 항상 전체가 포함돼요.
• 이미지에는 처음 2,000행이 포함돼요.
• 내장된 DejaVu 글꼴이 CJK 문자를 지원하지 않아 PDF 내보내기에서는 CJK 문자를 표시할 수 없어요.

라이선스

GPL-3.0. PDF 내보내기를 위해 DejaVu 글꼴(Bitstream Vera 라이선스)을 포함하고 있어요.