> For the complete documentation index, see [llms.txt](https://docs.wicle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wicle.io/analytics/dashboard/custom-dashboard/create-widget.md).
# ウィジェットを追加・編集する
カスタムダッシュボードで対話によりウィジェットを追加・編集し、レイアウトを調整する方法です。
左サイドバーで対象の[カスタムダッシュボード](/analytics/dashboard/custom-dashboard.md)を開いてから操作します。追加・編集する指標の対象、集計方法、見たい表示形式を伝えると、意図に合う案を確認しやすくなります。
## ウィジェットを追加する
{% hint style="warning" %}
プロジェクト内のウィジェット合計数が上限に達している場合は追加できません。ボタンにマウスを合わせると上限の案内が表示され、`上限設定を確認する`から確認画面へ移動できます。詳しくは[プロジェクトの上限設定](/organization-project/project-setting/limitation.md)をご覧ください。
{% endhint %}
1. ヘッダーの`ウィジェットを追加`をクリックします。右パネルに`ウィジェットを作成`が開きます。
2. 測りたい指標を文章で入力します（例：「日別UUの推移を折れ線で」「ランディングページ別のセッション一覧」）。
3. 既存のウィジェットを参考にする場合は、入力欄の`既存ウィジェットを参照`からダッシュボードとウィジェットを選びます。
4. AIが作成したチャート案のプレビューを確認します。修正したい場合は、変更内容を続けて伝えます。
5. `追加する`をクリックして保存します。追加しない場合は`破棄`をクリックします。
追加後も作成パネルで、続けて別のウィジェットを依頼できます。チャート案は、`追加する`をクリックするまでダッシュボードに保存されません。
{% hint style="info" %}
作成パネルには、よく使う依頼のサジェスト（日別UUの推移、流入チャネル別セッションなど）が表示されます。クリックして入力の起点にできます。
{% endhint %}
## 分析アシスタントから追加する
[チャットエージェント](/ai/agent.md)で生成したチャートを、カスタムダッシュボードのウィジェットとして追加できます。
1. 分析アシスタントでチャートが表示されたら、チャート上の`ダッシュボードに追加`をクリックします。
2. ダイアログで追加先を選びます。
* 既存のダッシュボードへ追加する場合は、`ダッシュボードを選択`から選びます。
* 新しいダッシュボードを作成する場合は、`新規作成`をオンにして`ダッシュボード名`を入力します。
3. 必要に応じて`ウィジェット名`を編集します。
4. `追加する`をクリックします。
追加が完了すると、トーストから`ダッシュボードを開く`で対象のダッシュボードへ移動できます。
{% hint style="info" %}
分析アシスタントから追加したウィジェットは、分析時の期間で`期間固定`されます。相対期間（例: 直近N日）も、登録時点の絶対期間に変換して固定されます。
{% endhint %}
## ウィジェットを対話で編集する
1. 対象ウィジェット右上の`⋯`メニューから`対話で編集`を選択します。
2. 開いた`ウィジェットを編集`パネルに、変更したい内容を伝えます（例：「棒グラフにして」「デバイス別に分けて」）。
3. プレビューを確認し、`更新する`をクリックして保存します。
{% hint style="info" %}
SQLだけ直す場合は、ウィジェットメニューの`SQLを編集`を使います。詳しくは [SQLを編集する](#edit-sql) をご覧ください。
{% endhint %}
## パラメータと連動させる
ウィジェットの作成・対話編集で、ダッシュボードに登録した[パラメータ](/analytics/dashboard/custom-dashboard.md#parameters)を使うように依頼できます。例えば「対象URLパラメータで、このウィジェットの集計対象ページを切り替えたい」と伝えます。連動させたい条件と、固定したままにする条件を具体的に指定します。
複数の既存ウィジェットをまとめて変更する場合は、[パラメータ設定から適用を指示](/analytics/dashboard/custom-dashboard.md#parameter-settings)できます。`ボードの変更案`が表示されたら、プレビューと集計条件を確認し、`選択した変更を保存`をクリックします。
連動後は、ウィジェットに`使用パラメータ`が表示されます。ダッシュボード上部で値を変えて`適用`すると、その値で再集計されます。
## チャート種別を変更する
ウィジェット右上のチャート種別アイコン（ツールチップ`チャート種別`）から、対話なしで種別を切り替えできます。
1. 対象ウィジェットのチャート種別アイコンをクリックします。
2. 一覧から種別を選択します。
切り替え可能な種別の例は次のとおりです。データの形に応じて、表示される選択肢が変わります。
* 系列なし: `折れ線` / `棒` / `円` / `ファネル`
* 系列あり: `折れ線` / `棒` / `積み上げ棒` / `グループ棒`
{% hint style="info" %}
散布図・ヒートマップ・数値・表など、互換のない種別ではチャート種別アイコンは表示されません。対話での編集からも種別変更を依頼できます。
{% endhint %}
## 名前・説明を変更する
1. 対象ウィジェットの`⋯`メニューから`名前・説明を変更`を選択します。
2. ウィジェット名（必須、200文字以内）と説明（任意、2,000文字以内）を入力します。
3. 保存します。
## 期間固定を変更する
ウィジェットは、特に指定がなければダッシュボード上部の期間セレクタに従います。次の場合に`期間固定`バッジが付き、上部の期間変更の影響を受けなくなります。
* 対話で絶対期間での固定を明示して作成・編集したとき
* 分析アシスタントからチャートを追加したとき
期間固定のウィジェットでは、`期間固定`の横に表示される日付をクリックして次の操作ができます。
* `カレンダーで期間を変更` — 固定する日付範囲を直接変更します
* `ダッシュボードの期間に合わせる` — 対話編集パネルが開き、期間固定を解除してダッシュボード上部の期間に従うよう依頼できます
{% hint style="info" %}
ダッシュボード上部の期間と同じ日付で作成しても、固定を明示しない限り期間固定にはなりません。
{% endhint %}
## SQLを編集する
`⋯`メニューの`SQLを編集`から、ウィジェット実行に使われるSQLを直接編集できます。列の追加やWHERE条件の微調整など、軽微な修正に向いています。指標の意図変更やチャート種別の変更、複雑な書き換えは`対話で編集`を使ってください。
1. 対象ウィジェットの`⋯`メニューから`SQLを編集`を選択します。
2. テキストエリアでSQLを編集します。
3. 必要に応じて`整形`や`SQLをコピー`を使います。
4. `SQLチェック`で検証するか、`保存して再実行`で保存してウィジェットを再実行します。
未保存の変更がある状態で閉じようとすると、確認ダイアログが表示されます。SQLが保存されていないウィジェットでは、対話で編集する案内が表示されます。
SQLは1〜10,000文字です。テーブルは次のプレースホルダで指定します。
* `{{user}}` / `{{session}}` / `{{event}}`
* グループ分析オプションが有効な場合は、`{{group}}` / `{{groupuser}}` も使えます
`{{session}}` / `{{event}}`を使うSQLには、`{{startDate}}`と`{{endDate}}`の両方が必要です。ダッシュボードで指定した期間を集計する場合は、例えば次のように期間条件を書きます。
```
session: start_date >= '{{startDate}}' AND start_date < DATE_ADD(DATE('{{endDate}}'), INTERVAL 1 DAY)
event: sync_date >= '{{startDate}}' AND sync_date < DATE_ADD(DATE('{{endDate}}'), INTERVAL 1 DAY)
```
`{{user}}` / `{{group}}` / `{{groupuser}}`だけのSQLでは、日付のプレースホルダは不要です。テーブルのプレースホルダは、バッククォートで囲まずに記述します（例：`FROM {{event}}`）。`CURRENT_DATE`などの現在日時を取得する関数は使えません。
{% hint style="info" %}
`SQLチェック`は保存せずに構文やルールを検証します。`保存して再実行`も保存前に同様の検証を行い、問題がある場合は保存されません。検証に使う期間は、期間固定ウィジェットでは固定期間、それ以外ではダッシュボード上部の現在の期間です。
{% endhint %}
### SQLからパラメータを参照する
パラメータが登録されている場合は、SQL編集画面に表示名・種類と、`@board_`で始まる参照名が表示されます。表示された参照名を使うと、SQLの条件にパラメータの値を指定できます。テーブル名や列名には使えません。
パラメータの値を変えても結果が変わらない場合は、SQLでそのパラメータを参照しているか確認します。空の値で絞り込みを解除したい場合も、SQL側にその条件が必要です。書き方に迷う場合は、[対話で編集](#use-parameters)して依頼できます。
## ウィジェットを削除する
1. 対象ウィジェットの`⋯`メニューから削除を選択します。
2. 確認ダイアログで削除を実行します。
レイアウト編集中は、ウィジェット右上の`×`からも削除できます。この場合の削除は、ヘッダーの`保存`を押すまで確定されません。
{% hint style="danger" %}
メニューから削除したウィジェットは復元できません。計測済みのユーザーやイベントのデータは削除されません。
{% endhint %}
## レイアウトを編集する
1. ヘッダーの`編集`をクリックします（ウィジェットが1件以上あるときのみ利用できます）。
2. ウィジェットをドラッグして位置を変更したり、端をドラッグしてサイズを変更したりします。
3. 削除などでできた空きを詰めたい場合は、`上に詰める` をクリックします。
4. `保存`をクリックして反映します。変更を破棄する場合は`取り消す`をクリックします。
{% hint style="info" %}
レイアウト編集中は、期間セレクタとウィジェット追加パネルは利用できません。また、画面幅が狭い場合はレイアウト編集できません。
{% endhint %}
## データを更新する
各ウィジェットの更新アイコンをクリックすると、そのウィジェットのデータを再取得できます。
## 会話について
### 作成チャット
ウィジェット作成時の対話は、ダッシュボード単位で保存されます。同じダッシュボードを再度開いても、前回の作成チャットを続けられます。
作成チャットは、プロジェクト内のメンバー全員で共有されます。他のメンバーが同じダッシュボードでウィジェットを追加した会話も、同じ履歴として表示されます。
### 編集チャット
ウィジェットの対話編集を開くたびに、新しい会話スレッドが始まります。
### 会話をやり直す
作成・編集パネルで`やり直す`をクリックし、確認画面で`クリア`を選択すると、会話履歴が消去されます。この操作は取り消せません。作成チャットはプロジェクトのメンバーと共有されているため、他のメンバーが参照する履歴もクリアされます。追加済みのウィジェットは残ります。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.wicle.io/analytics/dashboard/custom-dashboard/create-widget.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.