> ## Documentation Index
> Fetch the complete documentation index at: https://docs.core.sprocket.bz/llms.txt
> Use this file to discover all available pages before exploring further.

# データ抽出（SQL）と分析レポート

> SQL で BigQuery のデータを抜き出して集計し、結果をチャート付きの分析レポートとして保存・共有する方法です。

> この記事は Spumote のソースコードから生成した試験出力です。内容は確認中のため、正式な仕様は担当者に確認してください。

## この機能でできること

データ抽出は、SQL（データベースに条件を伝えるための言語）で BigQuery のデータを抜き出したり集計したりする画面です。画面の説明文は「SQL で条件を指定してデータを抜き出す・集計する。」です。結果をグラフ付きで保存しておく「分析レポート」もここに含まれます。

* SQL を書いて実行し、結果を表で確認する
* 実行前に「DryRun」で、エラーがないかと、どれくらいのデータを読むか（スキャン量）を確かめる
* 結果をコピー・CSV で保存する
* 過去に実行したクエリを履歴から見直す
* SQL の結果をチャート付きの「分析レポート」として保存し、チームで共有する

SQL を書かない方も、AI アシスタント（MCP）に「週ごとの注文数をグラフにして」のように頼むと、分析レポートを作ってもらえます。

## 画面の場所

データ › しらべる › データ抽出（SQL）

上部のピルで「クエリ」と「分析レポート」を切り替えます。「クエリ」の中には「実行」と「履歴」のタブがあります。

## クエリ画面の使い方

1. SQL エディタに SQL を書きます。「テーブルカタログから選択」でテーブルをクリックすると SELECT 文が自動で入り、「ファンクションカタログから選択」で関数の呼び出し文も入れられます。
2. 必要に応じて「整形」で SQL を見やすく整えたり、「列に展開」で `SELECT *` を列名の一覧に置き換えたりします。
3. 「DryRun」を押して、実行前チェックをします（下の「実行前チェック」参照）。
4. 「実行」を押します（Ctrl+Enter でも実行できます）。実行中は経過時間が表示されます。
5. 結果の表と、行数・処理したデータ量（MB）・実行時間が表示されます。「コピー」でタブ区切りのテキストとして、「CSV」で CSV ファイルとして保存できます。

画面には「よくあるクエリ」として SQL のひな形も用意されています。

### 実行前チェック（DryRun とスキャン量見積もり）

「DryRun」は、実際には実行せずに SQL を BigQuery に確認させる機能です。

* 成功すると「DryRun 成功」と「推定スキャンサイズ（MB）」、出力される列名が表示されます。BigQuery は読み込んだデータ量に応じて費用がかかるため、大きなテーブルを読む前に確認すると安心です。
* 文法の誤りや存在しないテーブルがあると、エラー内容が表示されます。

また、データを変更・削除する文（INSERT / UPDATE / DELETE などの DML・DDL）が含まれていると、実行前に「このクエリはデータを変更します」という確認が表示されます。取り消しはできないので注意してください。

### ロケーションと実行プロジェクト

* **ロケーション**: BigQuery のデータは保存場所（東京、US など）ごとに分かれています。実行場所を選ぶか、「自動判定」にすると参照するテーブルから BigQuery が推測します。「SET @@location を挿入」で SQL の先頭に場所の指定を入れることもできます。前回選んだ場所は組織ごとに記憶されます。
* **実行 PJ**: 費用を計上する GCP プロジェクトが登録されている場合、「実行 PJ:」で選べます。未選択なら既定のプロジェクトで実行されます。登録は「02-8 接続先の設定」で行います。

### 実行結果の詳細

実行に成功すると、結果の下に「ジョブ情報」（ジョブ ID、実行リージョン、クロスリージョンの有無、実行サービスアカウント、参照テーブルなど）が表示されます。別リージョンのテーブルを参照した場合は、その旨も表示されます。

### 履歴

「履歴」タブでは、過去の実行を一覧できます。開始・完了日時、実行時間、実行者、結果プレビューを確認でき、「GCP コンソールで表示」で BigQuery 側のジョブも開けます。

## 結果のダウンロード

* 画面の「CSV」「コピー」で保存されるのは、画面に表示された結果（最大 100 行）です。
* 100 行を超える結果を丸ごとファイルにしたい場合は、クエリ結果を CSV／JSON ファイルとして書き出す仕組みを使います。この書き出しは 1 回あたり読み込み 10GB までで、超えると「クエリのスキャンサイズが上限（10GB）を超えています」と表示されます。
* 定期的にファイルで受け渡す場合は、自動処理（ワークフロー）の出力を使います（「02-7 ファイル受け渡し」参照）。

## 機密列のマスキング

Spumote では、利用者のロール（役割）ごとに「機密レベル」（一般／機密）が決まっています。データ抽出の結果は、このレベルに応じて自動的に保護されます。

| ロールの機密レベル | 結果の見え方 |
| - | - |
| 機密 | 値がそのまま表示されます |
| 一般 | 結果の値が「\*\*\*\*」に置き換えて表示されます。また、機密領域の列は読み取れない状態でクエリが実行されます |

* この保護は画面表示だけでなく、履歴の結果プレビューやファイル書き出しにも適用されます。
* 機密レベルのロールを持つ利用者は、「実行 PJ:」で通常のサービスアカウントの登録を選び、あえて一般レベルとして実行することもできます（例: 機密データを含まない集計を通常の課金先で実行する）。

ロールの機密レベルは 設定 › 利用者と権限 › 権限 で確認できます。

## 分析レポート

分析レポートは、SQL の結果をチャート付きで保存した「スナップショット（保存時点の結果）」です。画面の説明は「SQL の結果をチャート付きで保存したスナップショット。Claude などの AI アシスタント ( MCP ) からも、この画面の「新規作成」からも作れます。」です。チャートは Spumote 側で描くため、閲覧に AI は必要ありません。

### 一覧

一覧には「タイトル」「種別」「行数」「更新」「作成経路」（Claude ( MCP )／管理画面）が並び、定期配信が設定されたレポートには「定期配信」と表示されます。

「表示形式」で「リスト」と「サムネイル」を切り替えられます。

* **リスト**: 表形式で一覧します（初期表示）。
* **サムネイル**: 保存済みチャートの縮小表示をカードで並べます。画面幅に応じて 1〜3 列です。表は先頭 4 行・3 列、ファネルは先頭のファネルだけを表示します。詳しい数値はレポートを開いて確認します。
* 選んだ表示形式はブラウザに記憶されます。サムネイル表示でも SQL は再実行されません。

### 作り方（画面から）

1. 「新規作成」を押し、「分析レポートを作成」画面を開きます。
2. 「タイトル」（必須）と「説明」を入力します。
3. 「SQL ( SELECT のみ )」に集計用の SQL を書きます。
4. 「チャート」で「種別」と、X 列・系列の列などを指定します。
5. 「実行して保存」を押します。保存時に SQL が 1 回実行され、マスク済みのスナップショットが保存されます（最長で数分かかります）。

### チャートの種別

| 種別 | 向いている使い方 |
| - | - |
| 折れ線 | 日別・週別の推移（X 列に日付、系列に値の列） |
| 棒 | カテゴリ別の比較。「積み上げ」も可能 |
| エリア | 推移の量感を見せる |
| 円 | 構成比（カテゴリの列＋値の列 1 つ） |
| ファネル | 段階ごとの到達数（例: 訪問 → カート → 購入） |
| 数値 | KPI を 1 つ大きく表示（先頭行の値） |
| 表 | 結果の全列を表で表示 |
| 都道府県地図 | 都道府県ごとの数値を日本地図の濃淡で表示 |

### 都道府県地図

* 「都道府県の列」に「東京都」「大阪府」など日本語の都道府県名が入った列、系列に数値の列を 1 つ指定します。SQL 側で都道府県ごとに 1 行に集計しておきます。
* 47 都道府県を固定の地図で描き、値が大きいほど濃い青になります。値がない地域は灰色の「データなし」になります。
* 不明な都道府県名・無効な数値・同じ地域の重複を含む行があると注記が出ます（重複地域は表示対象外）。
* ホバーや「都道府県別の数値」の一覧でも数値を確認できます。沖縄県は表示位置を調整し、一部の離島は省略・簡略化しています。

### 詳細画面でできること

* **チャート／結果テーブル／SQL** を確認します。SQL は「SQL を表示」で開き、「整形して表示」で読みやすくできます（保存済みの SQL は変わりません）。
* **更新**: SQL を再実行してスナップショットを取り直します。
* **期間を変えて表示**: SQL が `DATE(@date_from)` / `DATE(@date_to)` で期間を絞っている場合、「開始」「終了」を変えて「この期間で表示」で一時的に表示を切り替えられます。保存済みのレポートや定期配信は変わらず、「保存済みの結果に戻す」で元に戻せます。
* **定期配信**: レポートを定期的に出力する自動処理（ワークフロー）が紐付いている場合、その処理と出力先テーブルが表示されます。AI アシスタントに「このレポートを毎週月曜 9 時に配信して」と頼むと作成できます。
* **リンクをコピー**／**編集**／**削除**。保存済みの分析は、ホーム画面のダッシュボードにも追加できます。

## 活用例

* **キャンペーン前のターゲット数確認**: 条件に合う会員数を SQL で数え、DryRun でスキャン量を確かめてから実行します。
* **都道府県別の売上マップ**: 配送先の都道府県ごとに過去 30 日の売上を集計し、都道府県地図のレポートにして地域施策の検討に使います。
* **週次レポートの自動化**: AI アシスタントに週次の注文推移レポートを作らせ、毎週月曜に定期配信を設定します。

## 注意点・制限

* クエリの実行・DryRun には「data:bigquery:execute」権限が必要です。
* 画面に表示・保存される結果は最大 100 行です。
* SQL は 1 回あたり 1MB までです。クエリは最長 5 分で打ち切られます。
* データを変更する文（DML・DDL）も実行できますが、取り消しはできません。実行は監査ログに記録されます。
* 履歴で他の利用者の実行まで見られるのは owner（組織オーナー）のみで、それ以外の利用者には自分の実行だけが表示されます。
* 分析レポート: タイトルは 200 文字まで、説明は 2,000 文字まで。SQL は SELECT のみで、保存されるのは先頭 100 行です。
* 分析レポートの閲覧には「data:analysis:read」、作成・編集・更新には「data:analysis:write」と「data:bigquery:execute」の両方の権限が必要です。
* 分析レポートを削除すると、保存した SQL・チャート設定・スナップショットが消えます。定期配信の自動処理は残ります。
* 一般レベルのロールでは、結果の値は「\*\*\*\*」で表示されます（「機密列のマスキング」参照）。

## 詳しい設定（データ担当者向け）

* AI アシスタント（MCP）や API から分析レポートを保存・更新するときは、保存する行数（maxRows）を 1〜1000 で指定できます。画面から保存する場合は、先頭 100 行です。

## 関連ページ

* [02-1 データ一覧（BigQuery）](/dsv2/data-catalog)
* [02-3-1 自動処理（ワークフロー）：基本と作り方](/dsv2/workflow-basics)
* [02-7 ファイル受け渡し（S3・GCS・SFTP）](/dsv2/file-transfer)
* [02-8 接続先の設定](/dsv2/connections)
* [02-9 機密データの取り扱いと組織データセット](/dsv2/sensitive-data-and-org-dataset)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.