Codatum CLI

Appearance

グラフチャート ​

概要 ​

グラフチャート（template_type: 'GRAPH_CHART'）では、ノード間の関係性をネットワーク図として表示するグラフや、フロー量を可視化するサンキーダイアグラムを描画できます。ソース(source)とターゲット(target)にディメンションを、重み(weight)にメトリクスを指定して、ソースとターゲットの組み合わせごとに重みを集計して描画します。

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

render_type描画タイプ備考
GRAPHグラフソースとターゲットの関係をノードとエッジで描画
SANKEYサンキーソースからターゲットへのフロー量を帯の太さで描画
循環参照のない有向非巡回グラフ(DAG)が対象

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

設定例 ​

ユーザのページ遷移の可視化 ​

グラフの設定例 ​

ユーザのページ遷移を、遷移元(from_page)と遷移先(to_page)、遷移回数(transition_count)を元にグラフで表示する場合、次のように設定します。

md
:::sql-block
```sql
SELECT
  from_page,
  to_page,
  transition_count
FROM
  page_transitions
```

```yaml {.chart}
chartSettings:
  template_type: GRAPH_CHART
  component_settings:
    render_type: GRAPH
    source:
      - field: from_page
    target:
      - field: to_page
    weight:
      - field: transition_count
        aggregator: SUM
```
:::
  • データソースのSQLの実行結果として出力されるカラムを、チャート設定内で参照します
    • 以降の設定例では、データソースの定義は省略し、chartSettings の中身のみを記述しますが、チャート設定からは必ずデータソースのカラムを参照する必要があります
  • render_type: GRAPH を指定
  • source / target にそれぞれソース・ターゲットとなるディメンション（各1つのみ）を指定
  • weight にエッジの重みとなるメトリクス（1つのみ・任意）を指定
    • 省略した場合は、行数(COUNT(*))が重みとして利用されます

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

sql
SELECT
  from_page AS from_page___,
  to_page AS to_page___,
  SUM(IFNULL(transition_count, 0)) AS transition_count___sum
FROM
  /* データソースのSQL */
GROUP BY
  from_page___,
  to_page___
LIMIT
  1001

サンキーの設定例 ​

同じデータを render_type: SANKEY でサンキーダイアグラムとして表示する場合、次のように設定します。

yaml
template_type: GRAPH_CHART
component_settings:
  render_type: SANKEY
  source:
    - field: from_page
  target:
    - field: to_page
  weight:
    - field: transition_count
      aggregator: SUM
  • render_type: SANKEY を指定
  • サンキーは循環参照のない有向非巡回グラフ(DAG)が対象です
    • 例えば、 A → B → A のような循環がある場合は描画できずにエラーになります

データ加工オプション ​

フレーム機能の利用 ​

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

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

表示のカスタマイズ ​

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

render_type: GRAPH の場合、display_settings.layout_graph でグラフのレイアウトや見た目をカスタマイズできます。

ts
type LayoutGraphSettings = {
  non_directional?: boolean;  // ソースとターゲットの接続を双方向として扱う場合は true を指定
                              // (true の場合、A→B と B→A は1つのエッジに統合される)
  node_size?: 'TOTAL' | 'IN' | 'OUT';  // ノードサイズの計算対象を指定。デフォルトは 'TOTAL'
                                       // (non_directional: true の場合は無視されます)
                                       // 'TOTAL': ソースとターゲットの値の合計
                                       // 'OUT'  : ソースの値の合計
                                       // 'IN'   : ターゲットの値の合計
  node_size_calc_type?: 'LINEAR' | 'SQRT' | 'LOG'; // ノードサイズのスケーリング方法。デフォルトは 'SQRT'
  node_size_range?: {
    start: number;  // ノードの最小サイズ(px) 1〜64 で指定。デフォルトは 6
    end: number;    // ノードの最大サイズ(px) 1〜64 で指定。デフォルトは 24
  };
  node_color_by_weight?: boolean;  // ノードの色を重みと連動させる場合は true を指定
  edge_width_calc_type?: 'LINEAR' | 'SQRT' | 'LOG';  // エッジ幅のスケーリング方法。デフォルトは 'SQRT'
  edge_width_range?: {
    start: number;  // エッジの最小幅(px) 1〜32 で指定。デフォルトは 1
    end: number;    // エッジの最大幅(px) 1〜32 で指定。デフォルトは 6
  };
  repulsion?: number;   // ノード間の反発力 100〜5000 で指定。デフォルトは 1000
  gravity?: number;     // 中心への引力 0〜1.0 で指定。デフォルトは 0.1
  edge_length?: number; // 接続されたノード間の基準距離 10〜100 で指定。デフォルトは 30
};
  • ノードサイズ・エッジ幅は重みを元に算出されます
  • repulsion / gravity / edge_length は force-directed レイアウトのパラメータです

サンキーのカスタマイズ ​

render_type: SANKEY の場合、display_settings.layout_sankey でサンキーのレイアウトをカスタマイズできます。

ts
type LayoutSankeySettings = {
  orient?: 'horizontal' | 'vertical';  // サンキーの方向。デフォルトは 'horizontal'
};

ラベルの設定 ​

display_settings.label で各ノードのラベル表示をカスタマイズできます。

ts
type GraphLabelSettings = {
  hide?: boolean;          // ラベル全体を非表示にする場合は true を指定
  show_value?: boolean;    // 値を表示する場合は true を指定
  value_label_formatter?: FormatterSettings;
  label_width?: number;    // ラベルの最大幅(px)。デフォルトは 120
};

その他の設定 ​

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

型定義 ​

ts
type ChartSettings = {
  template_type: 'GRAPH_CHART';
  component_settings: ComponentSettingsCommon & {
    render_type: 'GRAPH' | 'SANKEY';
    source: [DimensionField];
    target: [DimensionField];
    weight?: [MetricsField];  // 省略した場合は COUNT(*) が利用されます
    frame?: [DimensionField];
    frame_layout?: FrameLayout;
  };
  display_settings?: {
    text?: TextSettings;
    frame?: FrameSettings;       // SANKEY の場合 independent_scale は指定不可
    layout_graph?: LayoutGraphSettings;    // for GRAPH
    layout_sankey?: LayoutSankeySettings;  // for SANKEY
    label?: GraphLabelSettings;
  };
};