Codatum CLI

Appearance

階層チャート ​

概要 ​

階層チャート（template_type: 'HIERARCHY_CHART'）では、階層構造を持つデータをツリー・ツリーマップ・サンバースト・ドリルダウン可能な棒グラフで描画できます。階層(hierarchies)に複数のディメンションを上位から順に指定し、値(value)にメトリクスを指定することで、階層に対する集計値を可視化できます。

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

render_type描画タイプ備考
TREEツリー階層を樹形図として描画
TREEMAPツリーマップ階層を入れ子の矩形として描画
SUNBURSTサンバースト階層を同心円として描画
BAR棒グラフ（ドリルダウン）棒グラフをクリックで階層をドリルダウン
2つ以上のディメンションをhierarchiesに指定

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

設定例 ​

地域別売上の階層可視化 ​

サンバーストの設定例 ​

国(country)・都道府県(prefecture)・市区町村(city)の階層に対する売上(sales_amount)を、サンバーストで表示する場合、次のように設定します。

md
:::sql-block
```sql
SELECT
  country,
  prefecture,
  city,
  sales_amount
FROM
  regional_sales
```

```yaml {.chart}
chartSettings:
  template_type: HIERARCHY_CHART
  component_settings:
    render_type: SUNBURST
    hierarchies:
      - field: country
      - field: prefecture
      - field: city
    value:
      - field: sales_amount
        aggregator: SUM
```
:::
  • データソースのSQLの実行結果として出力されるカラムを、チャート設定内で参照します
    • 以降の設定例では、データソースの定義は省略し、chartSettings の中身のみを記述しますが、チャート設定からは必ずデータソースのカラムを参照する必要があります
  • render_type: SUNBURST を指定（TREE / TREEMAP でも同じ設定で描画可能）
  • hierarchies に階層構造のディメンションを上位から順に指定（最低1つ必須）
  • value に集計対象のメトリクス（最大1つ・任意）を指定
    • 省略した場合は、行数(COUNT(*))が値として利用されます
  • ソートの詳細はデータのソートを参照してください
    • デフォルトは order_by: VALUE_DESC で、値が大きい順にソートされます

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

sql
SELECT
  country AS country___,
  prefecture AS prefecture___,
  city AS city___,
  SUM(IFNULL(sales_amount, 0)) AS sales_amount___sum
FROM
  /* データソースのSQL */
GROUP BY
  country___,
  prefecture___,
  city___
ORDER BY
  sales_amount___sum DESC
LIMIT
  1001

ドリルダウン可能な棒グラフの設定例 ​

同じデータを render_type: BAR でドリルダウン可能な棒グラフとして表示する場合、次のように設定します。

yaml
template_type: HIERARCHY_CHART
component_settings:
  render_type: BAR
  hierarchies:
    - field: country
    - field: prefecture
    - field: city
  value:
    - field: sales_amount
      aggregator: SUM
  • render_type: BAR を指定
  • hierarchies には2つ以上のディメンションを指定する必要があります
  • 棒をクリックすると、次の階層にドリルダウンします
  • BAR の場合、frame は指定できません

データ加工オプション ​

描画対象の件数制限 ​

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

フレーム機能の利用 ​

frame にディメンションを指定することで、その値ごとにチャートを分割して並べて表示できます。詳細はフレーム機能を参照してください。

  • render_type: BAR の場合、frame は指定できません
  • display_settings.frame.independent_scale は指定できません

表示のカスタマイズ ​

ラベルの設定（ツリー・ツリーマップ・サンバースト） ​

render_type が TREE / TREEMAP / SUNBURST の場合、display_settings.label で各ノードのラベル表示をカスタマイズできます。

ts
type HierarchyLabelSettings = {
  hide?: boolean;          // ラベル全体を非表示にする場合は true を指定
  show_value?: boolean;    // 値を表示する場合は true を指定
  value_label_formatter?: FormatterSettings;
  // for SUNBURST
  label_width?: number;    // ラベルの最大幅(px)。デフォルトは 120
};
  • value_label_formatter で値の書式を指定できます。詳細はフォーマッター設定を参照してください
  • label_width は render_type: SUNBURST の場合のみ有効です

NULL値の扱い（サンバースト） ​

render_type: SUNBURST の場合、display_settings.data.show_null で、階層の値が NULL の行を描画対象に含めるかどうかを指定できます。デフォルトは false で、NULL の行は描画対象から除外されます

軸のカスタマイズ（棒グラフ） ​

render_type: BAR の場合、display_settings.x_axis / display_settings.y_axis で軸の表示をカスタマイズできます。

  • 設定可能な項目は、軸の種類と設定を参照してください
  • X軸はカテゴリ軸、Y軸は数値軸として描画されます

棒のカスタマイズ（棒グラフ） ​

render_type: BAR の場合、display_settings.bar で棒の表示をカスタマイズできます。

  • formatter で値の書式を指定できます。詳細はフォーマッター設定を参照してください
  • value_label で棒の上に値ラベルを表示できます。詳細は系列の表示設定の ValueLabelSettings を参照してください
  • color で棒の色を指定できます。指定方法は色の指定を参照してください

その他の設定 ​

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

型定義 ​

描画タイプ：ツリー・ツリーマップ・サンバースト ​

ts
type ChartSettings = {
  template_type: 'HIERARCHY_CHART';
  component_settings: ComponentSettingsCommon & {
    render_type: 'TREE' | 'TREEMAP' | 'SUNBURST';
    hierarchies: DimensionField[];   // 最低1つ必須。配列の順序が階層の深さを表す（最初が最上位）
    value: [] | [MetricsField];      // 省略した場合は COUNT(*) が利用されます
    order_by?: AxisSortType;
    order_by_custom?: SqlOrderBy[];
    limit?: number;
    frame?: [DimensionField];
    frame_layout?: FrameLayout;
    limit?: number;
  };
  display_settings?: {
    text?: TextSettings;
    frame?: Omit<FrameSettings, 'independent_scale'>;
    label?: HierarchyLabelSettings;
    data?: {
      show_null?: boolean;   // 階層の値が NULL の行を描画対象に含める場合は true (SUNBURST のみ有効)
    };
  };
};

描画タイプ：棒グラフ（ドリルダウン） ​

ts
type ChartSettings = {
  template_type: 'HIERARCHY_CHART';
  component_settings: ComponentSettingsCommon & {
    render_type: 'BAR';
    hierarchies: DimensionField[];  // 2つ以上必須。配列の順序が階層の深さを表す（最初が最上位）
    value: [] | [MetricsField];     // 省略した場合は COUNT(*) が利用されます
    order_by?: AxisSortType;
    order_by_custom?: SqlOrderBy[];
    limit?: number;
  };
  display_settings?: {
    text?: TextSettings;
    x_axis?: AxisSettings;
    y_axis?: AxisSettings;
    bar?: {
      formatter?: FormatterSettings;
      value_label?: ValueLabelSettings;
      color?: PaletteColorName;
    };
  };
};