Codatum CLI

Appearance

ディメンションとメトリクス ​

概要 ​

ディメンション ​

型定義 ​

  • データソースとして、
    • カラムを指定する場合は field にカラム名を指定します
      • カラムのデータ型に応じて、ExtraDimensionFieldOptions による加工も可能です
    • カスタムSQLを指定する場合は is_custom_sql: true を指定し、 sql にSQL文字列を指定します
  • display_name を指定すると、チャートの凡例やツールチップの表示名を指定できます
ts
type DimensionField =
  | ({
      field: string;  // カラム名を指定
      display_name?: string;
    } & ExtraDimensionFieldOptions)
  | {
      is_custom_sql: true;
      sql: string;
      alias: string;
      display_name?: string;
    };

type ExtraDimensionFieldOptions =
  | {}
  | {
      enable_range_aggr: true;
      // データのバケット化を行う場合に指定
      // 生成されるSQL例: FLOOR(${field} / ${range_aggr_step}) * ${range_aggr_step})
      range_aggr_step: number;
    }
  | {
      enable_date_trunc: true;
      // 日付の端数切り捨てを行う場合に指定
      // 生成されるSQL例: DATE_TRUNC(${field}, ${date_trunc_arg})
      date_trunc_arg: 'YEAR' | 'MONTH' | 'WEEK';
    }
  | {
      enable_date_extract: true;
      // 日付の部分抽出を行う場合に指定
      // 生成されるSQL例: EXTRACT(${date_extract_arg} FROM ${field})
      date_extract_arg: 'YEAR' | 'MONTH' | 'DAY';
    }
  | {
      enable_datetime_trunc: true;
      // 日時型（TSなし）の端数切り捨てを行う場合に指定
      datetime_trunc_arg: 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE';
    }
  | {
      // 日時型（TSなし）の部分抽出を行う場合に指定
      enable_datetime_extract: true;
      datetime_extract_arg: 'YEAR' | 'MONTH' | 'DAY' | 'HOUR' | 'MINUTE';
    }
  | {
      // 日時型（TSあり）の端数切り捨てを行う場合に指定
      enable_timestamp_trunc: true;
      timestamp_trunc_arg: 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE';
      timestamp_timezone: string;
    }
  | {
      // 日時型（TSあり）の部分抽出を行う場合に指定
      enable_timestamp_extract: true;
      timestamp_extract_arg: 'YEAR' | 'MONTH' | 'DAY' | 'HOUR' | 'MINUTE';
      timestamp_timezone: string;
    };

設定例 ​

ts
// カラム category を指定する場合
{ field: 'category', display_name: 'カテゴリ' }

// 日付カラムを月単位で集計する場合
{
  field: 'sales_date',
  enable_date_trunc: true,
  date_trunc_arg: 'MONTH',
  display_name: '売上月',
}

// カスタムSQLを指定する場合
// SQLは利用するDWHのSQL構文に合わせて記述してください
{
  is_custom_sql: true,
  sql: 'IF(category = "FOOD", "FOOD", "OTHERS")',
  alias: 'food_or_others',
  display_name: 'カテゴリ（食品・その他）',
}

メトリクス ​

型定義 ​

  • データソースとして、
    • カラムを指定する場合、 aggregator で集計関数を指定します
    • カスタムSQLを指定する場合は is_custom_sql: true を指定し、 sql に集計関数を含めたSQL文字列を指定します
  • display_name を指定すると、チャートの凡例やツールチップの表示名を指定できます
ts
type MetricsField =
  | {
      field: string;  // カラム名を指定
      display_name?: string;
      aggregator: 'SUM' | 'AVG' | 'COUNT_UNIQUE' | 'COUNT' | 'MAX' | 'MIN' | 'ANY_VALUE';
    }
  | {
      is_custom_sql: true;
      sql: string;  // 集計関数を含める必要があります
      alias: string;
      display_name?: string;
    };

設定例 ​

ts
// カラム sales を SUM で集計する場合
{ field: 'sales', display_name: '売上合計', aggregator: 'SUM' }

// カラム id のユニーク数を集計する場合: COUNT(DISTINCT id) が生成されます
{ field: 'id', display_name: 'ユニーク数', aggregator: 'COUNT_UNIQUE' }

// カスタムSQLを指定する場合
// SQLは利用するDWHのSQL構文に合わせて記述してください
{
  is_custom_sql: true,
  sql: 'SUM(IF(category = "FOOD", sales, 0))',
  alias: 'food_sales_sum',
  display_name: '食品売上合計',
}

その他のカラム指定方法 ​

型定義 ​

  • ディメンションやメトリクスの他に、カラムの指定方法として RawField と AttributeField があります
    • RawField は、GROUP BY 句を伴わない SELECT 句で利用され、指定されたカラムをそのまま取得します
    • AttributeField は GROUP BY 句を伴う SELECT 句で利用され、同じグループ内のいずれかのデータを取得します（通常 MAX を利用）
ts
type RawField =
  | {
      field: string;
      display_name?: string;
    }
  | {
      is_custom_sql: true;
      sql: string;
      alias: string;
      display_name?: string;
    };

type AttributeField = RawField;

カラムを特定するキー ​

チャート設定内やSQL内で、特定のディメンションやメトリクスを参照する場合、次のキーを利用する場合があります。

ts
// `${field.toLowerCase()}___` or `${alias}`
type DimensionFieldInternalKey = `${string}___` | string;

// `${field.toLowerCase()}___${aggregator.toLowerCase()}` or `${alias}`
type MetricsFieldInternalKey = `${string}___${string}` | string;

// `${field}` or `${alias}`
type RawFieldInternalKey = string;

例えば、次のように変換されます。

ts
// ディメンション
{ field: 'category' } // => 'category___'
{ is_custom_sql: true, alias: 'food_or_others', ... } // => 'food_or_others'

// メトリクス
{ field: 'sales', aggregator: 'SUM' } // => 'sales___sum'
{ is_custom_sql: true, alias: 'food_sales_sum', ... } // => 'food_sales_sum'

// その他のカラム
{ field: 'id' } // => 'id'
{ is_custom_sql: true, alias: 'id', ... } // => 'id'