# データクエリ

チャートの設定パネルは、全体として「データクエリ」、「チャートオプション」、「インタラクションイベント」の3つのセクションに分かれています。一番下には、「キャンセル」、「プレビュー」、「保存」ボタンがあります。

まずは「データクエリ」パネルを見て、2つのクエリモード（ビルダー/SQL）と、よく使われる機能について理解を深めましょう。

## パネル構造
![clipboard-image-1761466636](https://static-docs.nocobase.com/clipboard-image-1761466636.png)

> ヒント: 現在のコンテンツをより簡単に設定するために、他のパネルを先に折りたたむことができます。

一番上は操作バーです。
- モード: ビルダー（グラフィカルでシンプル、便利です）/ SQL（手書きのステートメントで、より柔軟です）
- クエリ実行: クリックするとデータクエリリクエストが実行されます。
- 結果表示: データ結果パネルが開き、テーブル/JSON表示を切り替えられます。もう一度クリックするとパネルが閉じます。

上から順に、以下の項目があります。
- データソースとコレクション: 必須項目です。データソースとコレクションを選択します。
- メジャー: 必須項目です。表示する数値フィールドです。
- ディメンション: フィールド（日付/カテゴリ/地域など）でグループ化します。
- フィルター: フィルター条件（=、≠、>、<、含む、範囲など）を設定します。複数の条件を組み合わせることも可能です。
- ソート: ソートするフィールドと、昇順/降順を選択します。
- ページネーション: データ範囲と返される順序を制御します。

## ビルダーモード

### データソースとコレクションの選択
- 「データクエリ」パネルで、モードを「ビルダー」に設定します。
- データソースとコレクションを選択します。コレクションが選択できない場合や空の場合は、まず権限と作成済みかどうかを確認してください。

### メジャーの設定
- 1つ以上の数値フィールドを選択し、`Sum`、`Count`、`Avg`、`Max`、`Min` のいずれかの集計を設定します。
- よくある使用例: `Count` でレコード数をカウントし、`Sum` で合計を計算します。

### ディメンションの設定
- 1つ以上のフィールドをグループ化のディメンションとして選択します。
- 日付と時刻のフィールドは、月ごとや日ごとにグループ化しやすいように、`YYYY-MM` や `YYYY-MM-DD` などの形式を設定できます。

### フィルター、ソート、ページネーション
- フィルター: 条件（=、≠、含む、範囲など）を追加します。複数の条件を組み合わせることも可能です。
- ソート: フィールドとソート順（昇順/降順）を選択します。
- ページネーション: `Limit` と `Offset` を設定して、返される行数を制御します。デバッグ時には、`Limit` を小さく設定することをおすすめします。

### クエリ実行と結果表示
- 「クエリ実行」をクリックして実行します。結果が返されたら、「結果表示」で `Table / JSON` を切り替えて、列と値を確認します。
- チャートフィールドをマッピングする前に、ここで列名と型を確認してください。これにより、後でチャートが空になったりエラーが発生したりするのを防げます。

![20251026174338](https://static-docs.nocobase.com/20251026174338.png)

### 後続のフィールドマッピング

後で「チャートオプション」を設定する際に、選択したデータソースとコレクションのテーブルフィールドに基づいてフィールドをマッピングします。

## SQLモード

### クエリの記述
- 「SQL」モードに切り替えて、クエリステートメントを入力し、「クエリ実行」をクリックします。
- 例（日付ごとの注文合計金額）:
```sql
SELECT
  TO_CHAR(order_date, 'YYYY-MM') as mon,
  SUM(total_amount) AS total
FROM "order"
GROUP BY mon
ORDER BY mon ASC
LIMIT 100;
```

![20251026175952](https://static-docs.nocobase.com/20251026175952.png)

### クエリ実行と結果表示

- 「クエリ実行」をクリックして実行します。結果が返されたら、「結果表示」で `Table / JSON` を切り替えて、列と値を確認します。
- チャートフィールドをマッピングする前に、ここで列名と型を確認してください。これにより、後でチャートが空になったりエラーが発生したりするのを防げます。

### 後続のフィールドマッピング

後で「チャートオプション」を設定する際に、クエリ結果の列に基づいてフィールドをマッピングします。

> [!TIP]
> SQLモードに関する詳細については、「高度な使用法 — SQLモードでデータをクエリする」を参照してください。