Codatum CLI

Appearance

グリッドページ ​

概要 ​

  • ノートブックファイル内のグリッドページでは、ドキュメントページで定義したSQLブロックの実行結果やチャートを、ダッシュボードとしてレイアウトできます
  • グリッドページは以下の構造により記述します
    • yaml {.page} によるページ属性
    • :::grid-item によるグリッド内に配置する要素の定義
    • yaml {.grid-layout} によるグリッドのレイアウト定義

ページ属性 ​

  • ページ属性は yaml {.page} のコードブロックとして次のオブジェクト型で表現します
    • id はノートブックファイル内でユニークな値を指定します
      • 未指定の場合、 format 実行時に自動付与されます
    • width にはページ幅を指定します
      • デフォルトは { width_type: 'AUTO' } で、画面幅に合わせて伸縮します
    • columns にはグリッドの横分割数を整数（1-60）で指定します
      • デフォルトは 12 で、デフォルト値の場合は出力時に省略されます
      • グリッドレイアウトの width は、この分割数を基準とした列数になります
    • row_unit_px にはグリッドの縦1単位の高さを整数（10-120、単位px）で指定します
      • デフォルトは 60 で、デフォルト値の場合は出力時に省略されます
    • パラメータに関する説明は パラメータ を参照してください
ts
type GridPageAttrs = {
  type: 'GRID_PAGE';
  id: ObjectId;
  width?:
    | { width_type: 'AUTO' }
    | { width_type: 'FIXED'; fixed_width: 640 | 800 | 1024 | 1280 | 1366 | 1600 }
    | {
        width_type: 'RANGE';
        min_width?: 640 | 800 | 1024 | 1280 | 1366 | 1600;
        max_width?: 640 | 800 | 1024 | 1280 | 1366 | 1600;
      };
  columns?: number; // 横分割数（1-60、デフォルト12）
  row_unit_px?: number; // 縦1単位の高さpx（10-120、デフォルト60）

  // パラメータの説明を参照
  notebook_param_widget_values?: ParamWidgetValue[];
  page_param_widgets?: ParamWidget[];
  page_param_widget_values?: ParamWidgetValue[];
};

グリッド要素 ​

  • グリッドに配置する要素をコンテナディレクティブ :::grid-item により記述します
    • :::grid-item はグリッド内に配置する要素の数だけ記述します
    • 要素の属性を yaml {.attrs} のコードブロックとして記述します
      • id にはページ内でユニークな値を指定します（未指定の場合は自動生成されます）
        • 互換性のため、 ObjectId の他に Uuid も指定可能ですが、 ObjectId の使用を推奨します
      • type により、要素の種類を指定し、残りの属性は type により異なります
      • description を指定すると、グリッド内に ? アイコンが表示され、マウスオーバーで指定した説明が表示されます
    • 要素の本文を属性に続けてマークダウンで記述します
      • type によって要素の本文が必要な場合と不要な場合があります

見出し ​

  • 見出しは次の属性定義を持ちます
  • 要素の本文には h2, h3, h4 のいずれかの見出しを指定します
ts
type HeadingAttrs = {
  type: "HEADING";
  id: ObjectId | Uuid;
  description?: string;
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: HEADING
id: 69dac8455174dcb50b75eec1
description: Tooltip text here
```

## Example heading
:::

チャート ​

  • チャートは次の属性定義を持ち、ドキュメントページで定義したチャートを参照します
    • pageId でドキュメントページの id を、chartId で対象のチャートの id を指定します
    • overwriteParams を指定することで、パラメータの値を上書きできます
    • crossFilter については、クロスフィルタを参照してください
  • 要素の本文は不要です
  • jobId にはチャートのデータソースとして指定されたSQLブロックの、chartJobId にはチャート用のデータ加工に利用されたSQLのジョブリソースIDが付与されます
    • jobId, status 等の情報は、cdm notebook run の実行時に自動更新されます
      • コマンド経由で更新されるため、手動で書き換えないでください
    • status の詳細は以下の通りです
      • ERROR: 実行時にエラーが発生。errorMessage にエラーメッセージが付与されます
      • REMOVED: SQLが未実行、もしくはcdm notebook strip で実行状態が削除された
      • DISPATCHED: 上記以外の、実行中もしくは実行完了を意味します
ts
type ChartAttrs = {
  type: "CHART";
  id: ObjectId | Uuid;
  pageId: ObjectId;
  chartId: ObjectId;
  name?: string;  // チャート名を指定
  description?: string;
  crossFilter?: CrossFilter;
  overwriteParams?: OverwriteParam;
  hideFrame?: boolean;  // グリッドの枠線を非表示にするか否か
  hideName?: boolean;  // チャート名を非表示にするか否か

  // 以下はノートブックの実行時に自動更新
  jobId?: JobResourceId;
  state?: "DISPATCHED" | "ERROR" | "REMOVED";
  errorMessage?: string;
  chartJobId?: JobResourceId;
  chartJobQueryHash?: string;
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: CHART
id: 69dac8455174dcb50b75eec3
pageId: 69dac8455174dcb50b75eec1
chartId: 69dac8455174dcb50b75eec2
```
:::

SQLブロックの実行結果 ​

  • SQLブロックの実行結果は次の属性定義を持ち、ドキュメントページで定義したSQLブロックの実行結果を参照します
    • pageId でドキュメントページの id を、sqlId で対象のSQLブロックの id を指定します
    • overwriteParams を指定することで、パラメータの値を上書きできます
    • crossFilter については、クロスフィルタを参照してください
  • 要素の本文は不要です
  • jobId には sqlId で指定されたSQLブロックのジョブのジョブリソースIDが付与されます
    • 詳細についてはチャート を参照してください
ts
type SqlBlockResultAttrs = {
  type: "SQL_BLOCK_RESULT";
  id: ObjectId | Uuid;
  pageId: ObjectId;
  sqlId: ObjectId;
  name?: string;  // テーブル名を指定
  description?: string;
  crossFilter?: CrossFilter;
  overwriteParams?: OverwriteParam[];
  hideFrame?: boolean;  // グリッドの枠線を非表示にするか否か
  hideName?: boolean;  // テーブル名を非表示にするか否か

  // 以下はノートブックの実行時に自動更新
  jobId?: JobResourceId;
  state?: "DISPATCHED" | "ERROR" | "REMOVED";
  errorMessage?: string;
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: SQL_BLOCK_RESULT
id: 69dac8455174dcb50b75eec4
pageId: 69dac8455174dcb50b75eec1
sqlId: 69dac8455174dcb50b75eec2
```
:::

リッチテキスト ​

  • リッチテキストは次の属性定義を持ちます
  • 要素の本文には以下のマークダウン要素のみ指定できます（ドキュメントページの本文とは利用可能な要素が異なります）
    • パラグラフ
    • 空パラグラフ（::p）
    • リスト（箇条書き）(-, 1.)
      • 先頭の子要素はパラグラフ、以降の子要素はパラグラフ・引用・ネストしたリストを指定できます
    • 引用(>)
      • 子要素はパラグラフのみ指定できます
ts
type RichTextAttrs = {
  type: "RICH_TEXT";
  id: ObjectId | Uuid;
  name?: string;  // ブロック名を指定
  hideFrame?: boolean;  // グリッドの枠線を非表示にするか否か
  hideName?: boolean;  // ブロック名を非表示にするか否か
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: RICH_TEXT
id: 69dac8455174dcb50b75eec5
name: 補足事項
```

- 売上には発送後のキャンセル分は未反映
- 配送料は含まない
:::

スペーサー ​

  • スペーサーはレイアウトを調整するための空要素で、次の属性定義を持ちます
  • 要素の本文は不要です
ts
type SpacerAttrs = {
  type: "SPACER";
  id: ObjectId | Uuid;
  showOnMobileLayout?: boolean;
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: SPACER
id: 69dac8455174dcb50b75eec6
```
:::

パラメータ ​

  • パラメータは次の属性定義を持ち、定義済みのパラメータを値の入力タイルとして配置します
    • widgetId で参照するパラメータの id を指定します
    • scope で参照するパラメータのスコープを指定します
      • NOTEBOOK: フロントマターの notebook_param_widgets で定義されたパラメータ
      • PAGE: ページ属性の page_param_widgets で定義されたパラメータ
    • パラメータの定義については パラメータ を参照してください
  • このページの SQL・チャートから参照されていないパラメータは、入力フォームの代わりに未参照を示すメッセージが表示されます
  • widgetId と scope に対応するパラメータ定義がない場合、cdm notebook validate はエラーを返します。cdm notebook format --repair を実行すると、該当するグリッド要素はスペーサーへ置き換えられます
  • 要素の本文は不要です
ts
type ParameterAttrs = {
  type: "PARAMETER";
  id: ObjectId | Uuid;
  widgetId: ObjectId;
  scope: "NOTEBOOK" | "PAGE";
  hideFrame?: boolean;  // グリッドの枠線を非表示にするか否か
  hideName?: boolean;  // パラメータ名を非表示にするか否か
};

例 ​

md
:::grid-item
```yaml {.attrs}
type: PARAMETER
id: 69dac8455174dcb50b75eec7
widgetId: 507f1f77bcf86cd799439021
scope: NOTEBOOK
```
:::

グリッドレイアウト ​

  • グリッドレイアウトは次の GridLayout 型で表現される配列を yaml {.grid-layout} のコードブロックとして記述します
    • ref はグリッド要素の id を指定します
    • height はグリッド要素の高さを整数(n >= 1)で指定します
      • 実際の高さは縦1単位（ページ属性の row_unit_px、デフォルト 60）を基準とした {n * row_unit_px - 20}px になります
      • 要素ごとの初期値は次の通りです
        • 見出し、スペーサー: 1
        • パラメータ: 2
        • リッチテキスト: 3
        • チャート等のその他要素: 6
    • width はページの分割数（ページ属性の columns、デフォルト 12）を基準とした列数（整数）で、columns の直接の子（leaf / rows）にのみ指定します
      • 同一 columns 内の width 合計は、その columns が占める列数と一致させます
        • ページ最上段の columns: 合計 ページの分割数（デフォルト 12）
        • 親 rows が width: N のとき、その中の columns: 合計 N
      • validate では合計不一致をエラーにします
      • format では合計不一致の columns を均等幅に再分配して修正します（non-strict パース時。元の比率は保持されません）
      • 子数が親 width を超える columns は均等分割できないため、validate / format ともエラーにします
    • rows は columns の子としてのみ使用できます（ルート直下には置けません）
  • :::grid-item により定義されたグリッド要素で、レイアウトから未参照のものは format を実行するとレイアウトの末尾に自動追加されます
ts
type LeafNode = {
  type: 'leaf';
  ref: ObjectId | Uuid;
  height?: number;  // 未指定時は 6
};

type RowsNode = {
  type: 'rows';
  children: (LeafNode | ColumnsNode)[];
};

type ColumnsNode = {
  type: 'columns';
  children: ((LeafNode | RowsNode) & { width: number })[];
};

type GridLayout = (LeafNode | ColumnsNode)[];

例 ​

yaml
- type: columns
  children:
    - type: leaf
      ref: 69dac8455174dcb50b75eec1
      height: 2
      width: 8
    - type: leaf
      ref: 69dac8455174dcb50b75eec2
      height: 2
      width: 4
- type: columns
  children:
    - type: leaf
      ref: 69dac8455174dcb50b75eec3
      height: 4
      width: 4
    - type: leaf
      ref: 69dac8455174dcb50b75eec4
      height: 4
      width: 4
    - type: leaf
      ref: 69dac8455174dcb50b75eec5
      height: 4
      width: 4
- type: columns
  children:
    - type: rows
      width: 4
      children:
        - type: leaf
          ref: 69dac8455174dcb50b75eec6
          height: 5
        - type: leaf
          ref: 69dac8455174dcb50b75eec7
          height: 5
    - type: leaf
      ref: 69dac8455174dcb50b75eec8
      height: 10
      width: 8
- type: leaf
  ref: 69dac8455174dcb50b75eec9
  height: 8

Codatum CLI AIエージェントのための分析環境

© Codatum Inc.