# クエリを作成する

Sigma を使用して、ANSI SQL 標準でカスタムクエリを作成します。

アカウントで[レポートの表示権限](https://support.stripe.com/questions/can-i-invite-other-team-members-or-my-developer-to-use-my-stripe-account)を持つすべてのメンバーが、[Sigma クエリエディター](https://dashboard.stripe.com/sigma/queries)を使用して新しいクエリを作成したり、既存のクエリを変更したりできます。Stripe の大規模言語モデル (LLM) ベースのクエリアシスタントは、自然言語プロンプトから必要な SQL を生成することもできます。

## リソースのクエリ

エディターの左側のナビゲーションウィンドウには、クエリの構築に役立つツールセットが表示されています。以下を確認できます。

- 以前保存したクエリ。
- チームが保存したクエリ。
- データソースを検索する表スキーマ。
- Stripe クエリテンプレート。

### 保存済みのクエリとテンプレート

**レポート > 保存済み** には、自分とチームが以前に保存したクエリのリストが表示されます。**テンプレート** には、最も一般的な指標とレポートを表す一連のクエリ例が用意されています。保存したクエリまたはテンプレートを選択すると、そのクエリまたはテンプレートがクエリエディターにロードされ、**実行** をクリックすると結果を再生成して表示できます。

保存したクエリを独自のカスタムレポートの開始点として使用するには、オーバーフローメニュー (⋯) をクリックして **コピーを作成** を選択するか、エディターに読み込んで **コピーを作成** をクリックします。これにより、エディターでコンテンツを変更し、変更を新しいクエリとして[保存](https://docs.stripe.com/stripe-data/write-queries.md#saving-queries)できます。

## クエリを作成する

クエリエディターを開いて、以下を実行できます。

- 標準の ANSI SQL をエディターに直接記述します。
- 以前に保存したクエリまたは Stripe のテンプレートから既存のクエリを選択し、エディターで変更して、返されるデータを微調整します。

次のクエリでは、`balance_transactions` 表を使用して、返金に関連する最新の 5 つの残高取引に関する情報を取得します。

```sql
select
  date_format(created, '%Y-%m-%d') as day,
  id,
  amount,
  currency,
  source_id
from balance_transactions
where type = 'refund'
order by day desc
limit 5
```

**実行**をクリックしてクエリを実行すると、エディターの下のテーブルに結果が表示されます。クエリが複雑な場合は、完了して結果を表示するまで少し時間がかかることがあります。無効なクエリを実行するとエラーメッセージが生成され、その中でエラーの行番号と場所が示されます。

サンプルクエリの結果は、各行が特定の残高取引項目に対応する 5 つの行と、それらに関する要求された情報を返します。

| 日        | ID                  | 金額     | 通貨  | source_id          |
| -------- | ------------------- | ------ | --- | ------------------ |
| 2026/5/6 | txn_orWziM4j7CiRL8J | -1,000 | usd | re_orWziM4j7CiRL8J |
| 2026/5/6 | txn_orWziM4j7CiRL8J | -1,000 | usd | re_orWziM4j7CiRL8J |
| 2026/5/6 | txn_orWziM4j7CiRL8J | -1,000 | usd | re_orWziM4j7CiRL8J |
| 2026/5/6 | txn_orWziM4j7CiRL8J | -1,000 | eur | re_orWziM4j7CiRL8J |
| 2026/5/6 | txn_orWziM4j7CiRL8J | -1,000 | usd | re_orWziM4j7CiRL8J |

### テーブルを結合する

**主キー** または **外部キー** 型の列を、他の表の同様の列に結合できます。

- **主キー**: 表内の各レコードの一意の識別子 (ID) を表します。
- **外部キー**: 別の表の主キーを参照するデータを表します。

たとえば、`disputes` テーブルの `charge_id` 列 (外部キー) を、`charges` テーブルの `id` 列 (プライマリキー) に結合できます。
![](https://b.stripecdn.com/docs-statics-srv/assets/disputes.f293434123d316ff4fafe2524e9b2b0d.png)

テーブルを結合すると、データセットでより豊富な結果を返すことができます。たとえば、取引残高のサンプルを変更して `refunds` テーブルと結合し、より詳細な情報を提供することができます。

```sql
select
  date_format(date_trunc('day', balance_transactions.created), '%Y-%m-%d') as day,
  balance_transactions.amount,
  balance_transactions.currency,
  balance_transactions.source_id,
  refunds.charge_id
from
  balance_transactions
inner join refunds -- Joining these tables to retrieve additional information
on balance_transactions.source_id=refunds.id
where balance_transactions.type = 'refund'
order by day desc
limit 5
```

この拡張されたクエリは、返金が関連付けられている元の支払い ID を返すようになります。

| 日        | 金額     | 通貨  | source_id          | charge.id          |
| -------- | ------ | --- | ------------------ | ------------------ |
| 2026/5/6 | -1,000 | usd | re_orWziM4j7CiRL8J | ch_orWziM4j7CiRL8J |
| 2026/5/6 | -1,000 | usd | re_orWziM4j7CiRL8J | ch_orWziM4j7CiRL8J |
| 2026/5/6 | -1,000 | usd | re_orWziM4j7CiRL8J | ch_orWziM4j7CiRL8J |
| 2026/5/6 | -1,000 | eur | re_orWziM4j7CiRL8J | ch_orWziM4j7CiRL8J |
| 2026/5/6 | -1,000 | usd | re_orWziM4j7CiRL8J | ch_orWziM4j7CiRL8J |

## アシスタントを使用する

Stripe のクエリエディターには、LLM アシスタントが内蔵されており、自然言語プロンプトから標準の ANSI SQL を出力します。エディターでは以下のモードを実行できます。

- **生成**では、プロンプトの質問を使用して新しいクエリを作成し、エディターウィンドウにすでに読み込まれている SQL を上書きします。
- **編集**では、プロンプトの質問を使用してクエリエディターの SQL を変更します。

> #### モードを確認する
> 
> 推奨内容の精度を最大に高めるには、プロンプトに適したモードを選択してください。エディターにコンテンツが含まれる場合、モードは自動的に**編集**に切り替わります。その後モードを変更せずに新しいクエリを要求すると、エディターにすでにある情報に基づいて、生成される推奨内容が予期せず制限される可能性があります。

### アシスタントを使用する

1. ダッシュボードで [Sigma クエリエディター](https://dashboard.stripe.com/sigma/queries)を開きます。

1. **生成**モードを選択して、プロンプトフィールドに質問を入力します。アシスタントは以下を実行します。

   - クエリの推奨内容をエディターに読み込みます。
   - 推奨内容を説明するサマリーを表示します。
   - 推奨されたクエリを実行し、エディターの下のテーブルに結果を返します。
   - モードを**編集**に切り替えて、必要に応じて別の質問を行い、クエリを微調整できるようにします。

1. 必要な情報を取得できるまで、引き続きアシスタントを使用して結果データを表示します。

次のスクリーンショットは、このドキュメントの冒頭に示したクエリ例と同じ SQL がプロンプトによってどのように生成されたかを示しています。
![アシスタントの表示と結果を示します。](https://b.stripecdn.com/docs-statics-srv/assets/sigma-assistant.5f0ca3dae331a32c4c58cf6ceecdbf65.png)

推奨内容を修正するための追加質問には、以下のようなものがあります。

- これらの結果を金額で並べ替えます。
- automatic_transfer 列や reporting_category 列を含めないでください。
- 各取引の顧客を確認できますか？

> #### Connect のデータを明示的にリクエストする
> 
> 連結アカウントに関するデータを要求するときは、クエリで連結アカウントを明示的に指定します。例: *先月、連結アカウントからの新規サブスクリプションはいくつありましたか？*

### チャットの履歴を表示する

Sigma は、対象のクエリのチャット履歴に、アシスタントとのやり取りをすべて保存します。エディターの右上にある :history: ボタンをクリックして、チャット履歴スライダーを開きます。

チャット履歴では、クエリの期間 (現在のセッションだけではなく) 内にアシスタントに入力された各プロンプトと、アシスタントの応答を確認できます。**SQL を表示**をクリックすると、プロンプトに関連付けられた SQL の推奨を確認できます。開いたときに**エディターで表示**をクリックすると、その推奨をメインのエディターウィンドウに再度読み込むことができます。

### 制限事項

- クエリエディターのアシスタントは、英語での質問にのみ回答します。
- クエリエディターのアシスタントは、Stripe スキーマに関連する質問にのみ回答します。「Stripe のロゴは何色ですか？」や、「今日のサンフランシスコの天気は？」などの一般的な質問には回答できません。

### フィードバックを送る

エディターと結果テーブルの間の**この対応はお役に立ちましたか？**というプロンプトに応答して、アシスタントの継続的な改善にご協力ください。

1. **はい**または**いいえ**をクリックします。

1. アシスタントの対応についての具体的な詳細と、改善すべき点を入力してください。推奨内容の正確さ、UI、アシスタントを使用する際のその他の機能についてなど、あらゆるご意見をお待ちしております。

### トレーニングデータへの同意

Sigma Assistant を使用することで、お客様のチャットへの入力を Stripe が記録し、Sigma Assistant の機能のトレーニングと改善のために Stripe が利用することに同意したとみなされます。このような目的でのチャットへの入力の使用を望まない場合は、[設定](https://dashboard.stripe.com/settings/sigma)でオプトアウトできます。

## クエリ結果を表示・ダウンロードする

日、週、または月単位で[クエリをスケジュール設定](https://docs.stripe.com/stripe-data/schedule-queries.md)できます。結果はメールまたは *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) イベントとして送信されます。

クエリ結果は、エディターの下のテーブルに表示されます。以下の操作を実行できます。

- 最大 1,000 件の結果を表示できます。
- 列ヘッダーをクリックして、結果を並べ替えます。
- 結果を読みやすくするために、各列のサイズを変更します。

クエリの結果が 10,000 件未満の場合は、視覚化したチャートを作成することもできます。以下が可能です。

- カスタム Y 軸および X 軸を使用して折れ線グラフまたは棒グラフを作成します。
- 任意のテーブル列でグループ化する

クエリにチャートを保存すると、クエリを実行するたびに、選択した設定でチャートが表示されます。チャートはクエリの作成者のみ編集することができます。

金額は USD ではセント、JPY では円のように、決済通貨の最小単位で表示されます。たとえば、通貨が `usd` で金額が `1,000` の場合、10 USD に相当します。

**CSV をダウンロード**をクリックして、スプレッドシートアプリケーションやその他のレポートツールで使用するために結果をエクスポートします。ダウンロードされた CSV にはすべてのクエリ結果が含まれるため、表示可能な結果は 1,000 件に制限されません。

## API からクエリを実行する (非公開ベータ)

クエリを保存し、Sigma API を使用して独自の環境でプログラム実行できます。

## クエリを保存する

クエリを実行したら、**保存** をクリックします。Stripe クエリの編集可能なタイトルが自動的に生成されます。

### クエリを共有する

自分自身が保存したクエリは **レポート > 保存済み** に追加され、アカウントのすべてのチームメンバーが利用できます。保存されたそれぞれのクエリには一意の URL が設定されるため、**共有** をクリックして共有できます。このリンクを、定期的に使用する特定のレポートへのショートカットとして使用したり、Stripe アカウントの他のチームメンバーと直接共有したりすることができます。

クエリはチームメンバーとのみ共有できます。また、共有されたクエリは読み取り専用であるため、他のチームメンバーはお客様が作成したクエリを変更できません。チームメンバーがクエリに変更を加えるには、各自コピーを作成してそれを編集できます。