Codatum CLI

Appearance

XYチャート ​

概要 ​

XYチャート（template_type: 'XY_CHART_V2'）では、折れ線グラフ・棒グラフ・面グラフ・散布図・バブルチャート、およびそれらの複合チャートを表示できます。X軸(x)にディメンション、Y軸の値(views[].ys)にメトリクスを指定して、X軸の値ごとにY軸の値を集計して描画します。

指定可能な描画タイプは次の通りです。

render_type描画タイプ備考
LINE折れ線グラフ-
BAR棒グラフ-
POINT散布図-
BUBBLEバブルチャートバブルサイズをメトリクスとして追加指定
STACKED_BAR積み上げ棒グラフ複数メトリクスを積み上げて描画
STACKED_AREA積み上げ面グラフ（同上）
PERCENT_BAR100% 積み上げ棒グラフ複数メトリクスの合計が100%となるように
構成比を計算して積み上げて描画
PERCENT_AREA100% 積み上げ面グラフ（同上）

事前にチャート設定についても確認してください。

設定例 ​

売上構造と取引件数の分析 ​

複合チャートの設定例 ​

月別の売上を原価(cost_amount)と粗利(gross_profit)に分解して積み上げ棒グラフとして表示し、複合チャートとして取引件数(transaction_count)を折れ線で重ねて表示する場合、次のように設定します。

md
:::sql-block
```sql
SELECT
  sales_date,
  cost_amount,
  gross_profit,
  transaction_count
FROM
  sales_data
```

```yaml {.chart}
chartSettings:
  template_type: XY_CHART_V2
  component_settings:
    x:
      - field: sales_date
        enable_date_trunc: true
        date_trunc_arg: MONTH
    views:
      - view_id: 69e7d77cd95ae3b4f837630a
        render_type: STACKED_BAR
        ys:
          - field: cost_amount
            aggregator: SUM
          - field: gross_profit
            aggregator: SUM
      - view_id: 69e7d781cf4947a8fc1db549
        render_type: LINE
        ys:
          - field: transaction_count
            aggregator: SUM
        independent: true
```
:::
  • データソースのSQLの実行結果として出力されるカラムを、チャート設定内で参照します
    • 以降の設定例では、データソースの定義は省略し、chartSettings の中身のみを記述しますが、チャート設定からは必ずデータソースのカラムを参照する必要があります
  • X軸には sales_date カラムを月単位で丸めるディメンションを指定
  • Y軸には、複合チャートとして複数の views を指定し、
    • view_id には ObjectId 形式のユニークなIDを生成して指定
    • 1つ目の view では、原価(cost_amount)と粗利(gross_profit)を積み上げて描画
      • 積み上げたいメトリクスを ys にまとめて指定
    • 2つ目の view では、取引件数(transaction_count)を折れ線で描画
      • 取引件数のY軸を原価・粗利（金額）とは別スケールで描画するために independent: true を指定
      • independent: true を指定すると、その view のスケールは他から独立し、独自のY軸が右側に描画されます

上記の例では、次のようなSQLが生成され、チャート用のデータ加工が行われます。

sql
SELECT
  DATE_TRUNC(sales_date, MONTH) AS sales_date___,
  SUM(IFNULL(cost_amount, 0)) AS cost_amount___sum,
  SUM(IFNULL(gross_profit, 0)) AS gross_profit___sum,
  SUM(IFNULL(transaction_count, 0)) AS transaction_count___sum
FROM
  /* データソースのSQL */
GROUP BY
  sales_date___
ORDER BY
  sales_date___ ASC
LIMIT
  1001

X軸の種類 ​

XYチャートでは、X軸のデータ型と描画タイプでX軸の種類が決まります。 上記の例では、X軸に日付型のカラムを指定しているため、日時軸となります。

X軸のデータ型描画タイプX軸の分類
日付・日時型(任意)日時軸
数値型散布図・バブル・折れ線のみ数値軸
数値型棒・面・積み上げを含むカテゴリ軸
上記以外(任意)カテゴリ軸

なお、Y軸は数値軸で固定です。 各軸の特徴と設定は、軸の種類と設定を参照してください。

複合チャートの分割表示 ​

上記の設定では、積み上げ棒グラフと折れ線グラフが同一の描画領域を共有します。 次のように split_by_view: true を指定すると、X軸を共有しつつ、views ごとにY軸を縦に並べて描画できます。

  • 以下の設定の場合、上側に積み上げ棒グラフが、下側に折れ線グラフが描画されます（上下に2つの描画領域が並びます）
  • split_by_view: true を指定すると views[].independent の設定は無視されます
yaml
template_type: XY_CHART_V2
component_settings:
  # x は省略
  views:
    - view_id: 69e7d77cd95ae3b4f837630a
      render_type: STACKED_BAR
      ys:
        - field: cost_amount
          aggregator: SUM
        - field: gross_profit
          aggregator: SUM
    - view_id: 69e7d781cf4947a8fc1db549
      render_type: LINE
      ys:
        - field: transaction_count
          aggregator: SUM
  split_by_view: true

カテゴリ別の売上分析 ​

棒グラフの設定例 ​

カテゴリ(sales_category)別の売上(sales_amount)を、売上が大きい順に棒グラフで表示する場合、次のように設定します。

yaml
template_type: XY_CHART_V2
component_settings:
  x:
    - field: sales_category
  views:
    - view_id: 69e7e3a6c718bb4dfcbea4c6
      render_type: BAR
      ys:
        - field: sales_amount
          aggregator: SUM
  order_by: VALUE_DESC

上記の例では、次のようなSQLが生成され、チャート用のデータ加工が行われます。

sql
SELECT
  sales_category AS sales_category___,
  SUM(IFNULL(sales_amount, 0)) AS sales_amount___sum
FROM
  /* データソースのSQL */
GROUP BY
  sales_category___
ORDER BY
  sales_amount___sum DESC
LIMIT
  1001

生成されるSQLの ORDER BY の決定ロジック ​

  • X軸に文字列型のカラムもしくは、カスタムSQLが指定された場合、
    • order_by や order_by_custom によってデータ加工用のSQLの ORDER BY 句を変更できます
      • 例えば、上記の棒グラフの設定では、 order_by: VALUE_DESC を指定しているため、売上が大きい順にソートされます
    • 詳細はデータのソートを参照してください
      • XYチャートの場合、ラベルにはX軸の値が、値には views[0].ys[0] のメトリクス値が利用されます
  • 上記以外の場合、データ加工用のSQLのソート順はX軸の値の昇順で固定となります
    • 例えば、シナリオAの場合、X軸に指定した売上月の昇順でソートされています

グループ化の設定例 ​

カテゴリ別の売上の月次推移を積み上げ棒グラフで表示する場合、次のように設定します。

yaml
template_type: XY_CHART_V2
component_settings:
  x:
    - field: sales_month
  views:
    - view_id: 69e7dc355a421754a0ae6d01
      render_type: STACKED_BAR
      ys:
        - field: sales_amount
          aggregator: SUM
  group_by:
    - field: sales_category
  • group_by にディメンションを指定することで、そのディメンションの値ごとに views[].ys のメトリクスを分割できます。
    • この場合では、sales_category の値ごとの sales_amount の合計値が積み上げ棒グラフで描画されます。
  • group_by によるメトリクスの分割は、 views のすべてのメトリクスに一律で適用されます（SQLの GROUP BY 句に指定されるため）
    • group_by を指定する場合、メトリクスの数が増えすぎて視認性が低下しないように、メトリクスは1つに限定することをお勧めします。
  • group_by を指定している場合、 group_sort や group_sort_custom により、系列・凡例の並び順を指定できます

フレーム機能の利用 ​

カテゴリ別の売上の月次推移を表示する場合、グループ化の他に、フレーム機能を利用することもできます。

次のように設定すると、sales_category の数だけ、売上の月次推移グラフがグリッド状に並びます。

  • グリッドレイアウトの場合、最大16チャートまでの表示となるので、 sales_category の数に注意してください
  • split_by_view: true とは併用できず、指定されている場合、フレームの設定は無視されます
yaml
template_type: XY_CHART_V2
component_settings:
  x:
    - field: sales_month
  views:
    - view_id: 69e7dc355a421754a0ae6d01
      render_type: BAR
      ys:
        - field: sales_amount
          aggregator: SUM
  frame:
    - field: sales_category
  frame_layout: GRID

データ加工オプション ​

描画対象の件数制限 ​

limit により、描画対象のデータの件数を制限できます。詳細はデータの件数制限を参照してください。

表示のカスタマイズ ​

転置表示 ​

display_settings.transpose: true を指定すると、X軸とY軸を転置して描画できます。

  • 転置表示は、X軸の種類がカテゴリ型の場合のみ有効です
  • 棒グラフの設定例では、転置表示を利用することで、カテゴリ(sales_category)が左側に縦に並んで表示されるようになり、X軸のラベルが見やすくなります
    • X軸のラベルの視認性に課題がある場合、この転置表示を利用するか、後述の軸のカスタマイズで、ラベルを回転させることで改善できます

軸のカスタマイズ ​

  • X軸のカスタマイズは、display_settings.x_axis で設定できます
  • Y軸のカスタマイズは、display_settings.y_axis で設定できます
    • ただし、 split_by_view: true を指定している場合、もしくは views[].independent: true を指定している場合は、display_settings.independent_axes で view ごとに view_id をキーにして設定します
  • 設定可能な項目は、軸の種類と設定を参照してください

系列のカスタマイズ ​

views[].ys に指定したメトリクスごとのカスタマイズは、display_settings.series で設定できます

  • 対応するメトリクスを指定するために ${view_id}-${MetricsFieldInternalKey} 形式のキーを利用します
  • カスタマイズ可能な項目は、メトリクスの描画タイプによって異なります
    • BUBBLE: BubbleSettings でカスタマイズできます
    • POINT: PointSettings でカスタマイズできます
    • LINE: LineSettings でカスタマイズできます
    • AREA, STACKED_AREA, PERCENT_AREA: AreaSettings でカスタマイズできます
    • 詳細は系列の表示設定を参照してください

その他の設定 ​

  • フレーム表示時の設定(display_settings.frame)についてはフレーム機能を参照してください
  • 次のカスタマイズについてはその他のチャート設定を参照してください
    • テキスト設定(display_settings.text)
    • 凡例設定(display_settings.legend)
    • データズーム設定(display_settings.data_zoom)

型定義 ​

ts
type ChartSettings = {
  template_type: 'XY_CHART_V2';
  component_settings: ComponentSettingsCommon & {
    x: [DimensionField];
    views: {
      view_id: ObjectId;
      render_type:
        | 'LINE'
        | 'BAR'
        | 'POINT'
        | 'BUBBLE'
        | 'STACKED_BAR'
        | 'PERCENT_BAR'
        | 'AREA'
        | 'STACKED_AREA'
        | 'PERCENT_AREA';
      ys: MetricsField[];
      bubble_size?: [MetricsField] | []; // `render_type: "BUBBLE"` の場合、バブルのサイズを指定
      independent?: boolean;
    }[];
    split_by_view?: boolean;
    group_by: DimensionField[] | [];
    group_sort?: GroupSortType;
    group_sort_custom?: [AttributeField];
    order_by?: AxisSortType;
    order_by_custom?: SqlOrderBy[];
    frame?: [DimensionField];
    frame_layout?: FrameLayout;
    limit?: number;
  };
  display_settings: {
    transpose?: boolean;
    text?: TextSettings;
    legend?: LegendSettings;
    data_zoom?: DataZoomSettings;
    frame?: FrameSettings;
    x_axis?: AxisSettings;
    y_axis?: AxisSettings; // split_by_view が true の場合は independent_axes を利用
    independent_axes?: { [view_id: ObjectId]: AxisSettings };
    series?: Record<
      `${ObjectId}-${MetricsFieldInternalKey}`, // `${view_id}-${MetricsFieldInternalKey}`
      {
        formatter?: FormatterSettings;
        value_label?: ValueLabelSettings;
        stats?: SeriesStats;
        trendline?: TrendlineSettings;
        color?: PaletteColorName;
      } & BubbleSettings &
      PointSettings &
      LineSettings &
      AreaSettings;
    >;
  };
}