パラメータ

概要

パラメータを定義すると、ドキュメントページやグリッドページの上部に、パラメータの入力フォームが表示されるようになります
パラメータは、ドキュメントページのSQLブロック内からプレースホルダを通して参照することができます

スコープ

パラメータには利用可能な範囲の違いによって、次の2つのスコープがあります。いずれのスコープでも、パラメータの値はページごとに保持されます。

ノートブック共通
- 全ページで共通して利用できるパラメータ
- パラメータ定義は、ノートブック属性としてフロントマターの notebook_param_widgets?: ParamWidget[] に保持されます
- パラメータの値は、各ページ属性の notebook_param_widget_values?: ParamWidgetValue[] に保持されます
ページ固有
- そのページ内でのみ利用できるパラメータ
- パラメータ定義は、各ページ属性の page_param_widgets?: ParamWidget[] に保持されます
- パラメータの値は、各ページ属性の page_param_widget_values?: ParamWidgetValue[] に保持されます

型定義

パラメータ定義は次の ParamWidget 型で表現され、
- id はスコープごと（ノートブックファイル内、ページ内）にユニークな値を指定します
- label はパラメータの名前であり、入力フォームのラベルとして表示されます
- type にパラメータの種類を指定します
  - それぞれのパラメータの種類に応じて settings や defaultValue が異なります
パラメータの値は、 ParamWidgetValue 型で表現され、
- id は ParamWidget の id と一致させます
- value はパラメータの値で、対応する ParamWidget の type に応じた値の型が入ります

interface ParamWidget {
  id: ObjectId;
  type: ParamWidgetType;
  label: string;
  settings?: ParamWidgetSettings;
  defaultValue?: ParamWidgetDefaultValue;
};

interface ParamWidgetValue {
  id: ObjectId;
  value: unknown;
};

パラメータの種類

パラメータには、表示されるフォームの違いによって、次の種類があります。

テキスト入力

単一のテキストを入力できるフォームを表示します
escapeType: 'STRING' のプレースホルダから参照できます

interface TextInputParamWidget extends ParamWidget {
  type: "TEXT_INPUT";
  settings: {
    description?: string;
    placeholder?: string;
  },
  defaultValue?: {
    type: 'FIXED';
    fixedValue: string;
  };
};

interface TextInputParamWidgetValue extends ParamWidgetValue {
  value: string;
};

テキスト複数入力

複数行・複数値のテキストを入力できるフォームを表示します
escapeType: 'STRING_ARRAY' のプレースホルダから参照できます

interface TextMultiInputParamWidget extends ParamWidget {
  type: "TEXT_MULTI_INPUT";
  settings: {
    description?: string;
    placeholder?: string;
  };
  defaultValue?: {
    type: "FIXED";
    fixedValue: string[];
  };
};

interface TextMultiInputParamWidgetValue extends ParamWidgetValue {
  value: string[];
};

テキスト選択

候補から 1 件の文字列を選ぶフォームを表示します
escapeType: 'STRING' のプレースホルダから参照できます
SelectOptionsSettings に選択肢の生成方法を指定します
- 詳細は選択肢の生成方法を参照してください

interface TextSelectParamWidget extends ParamWidget {
  type: "TEXT_SELECT";
  settings: {
    description?: string;
    placeholder?: string;
  } & SelectOptionsSettings;
  defaultValue?: {
    type: "FIXED";
    fixedValue: string;
  };
};

interface TextSelectParamWidgetValue extends ParamWidgetValue {
  value: string;
};

テキスト複数選択

候補から複数の文字列を選ぶフォームを表示します
escapeType: 'STRING_ARRAY' のプレースホルダから参照できます
SelectOptionsSettings に選択肢の生成方法を指定します
- 詳細は選択肢の生成方法を参照してください

interface TextMultiSelectParamWidget extends ParamWidget {
  type: "TEXT_MULTI_SELECT";
  settings: {
    description?: string;
    placeholder?: string;
  } & SelectOptionsSettings;
  defaultValue?: {
    type: "FIXED";
    fixedValue: string[];
  };
};

interface TextMultiSelectParamWidgetValue extends ParamWidgetValue {
  value: string[];
};

数値入力

単一の数値を入力できるフォームを表示します
escapeType: 'NUMBER' のプレースホルダから参照できます

interface NumberInputParamWidget extends ParamWidget {
  type: "NUMBER_INPUT";
  settings: {
    description?: string;
    placeholder?: string;
    min?: number;
    max?: number;
    step?: number;
  };
  defaultValue?: {
    type: "FIXED";
    fixedValue: number;
  };
};

interface NumberInputParamWidgetValue extends ParamWidgetValue {
  value: number;
};

数値選択

候補から 1 件の数値を選ぶフォームを表示します
escapeType: 'NUMBER' のプレースホルダから参照できます
SelectOptionsSettings に選択肢の生成方法を指定します
- 詳細は選択肢の生成方法を参照してください

interface NumberSelectParamWidget extends ParamWidget {
  type: "NUMBER_SELECT";
  settings: {
    description?: string;
    placeholder?: string;
  } & SelectOptionsSettings;
  defaultValue?: {
    type: "FIXED";
    fixedValue: number;
  };
};

interface NumberSelectParamWidgetValue extends ParamWidgetValue {
  value: number;
};

日付入力

単一の日付を選ぶフォームを表示します
escapeType: 'DATE' のプレースホルダから参照できます

interface DateInputParamWidget extends ParamWidget {
  type: "DATE_INPUT";
  settings: {
    description?: string;
    placeholder?: string;
    unit?: "DATE" | "WEEK" | "MONTH" | "YEAR"; // 未指定時は DATE
    unitRefPoint?: "START" | "END"; // 未指定時は START
    dayStartOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6; // 未指定時は 0
    absoluteValidRange?: { lower?: string; upper?: string };
    relativeValidRange?: { lower?: number; upper?: number };
  };
  defaultValue?: {
    type: "FIXED";
    fixedValue: string; // YYYY-MM-DD
  } | {
    type: "RELATIVE_DATE";
    relativeDateOffset: number;  // 今日を基準に何日ずらすか指定（0:今日、-1:昨日、1:明日）
  };
};

interface DateInputParamWidgetValue extends ParamWidgetValue {
  value: string; // YYYY-MM-DD
};

日付範囲

開始日・終了日を選ぶフォームを表示します
開始日を escapeType: 'DATE' のプレースホルダから ${ParamWidget.id}.0 で、終了日を ${ParamWidget.id}.1 で参照できます

interface DateRangeParamWidget extends ParamWidget {
  type: "DATE_RANGE";
  settings: {
    description?: string;
    unit?: "DATE" | "WEEK" | "MONTH" | "YEAR";
    unitRefPoint?: "START" | "END";
    dayStartOfWeek?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
    absoluteValidRange?: { lower?: string; upper?: string };
    relativeValidRange?: { lower?: number; upper?: number };
  };
  defaultValue?: {
    type: "FIXED";
    fixedValue: [string, string];  // ['YYYY-MM-DD', 'YYYY-MM-DD']
  } | {
    type: "RELATIVE_DATE_RANGE";
    relativeDateRangeOffsetStart: number;  // 今日を基準に何日ずらすか指定（0:今日、-1:昨日、1:明日）
    relativeDateRangeOffsetEnd: number;  // 同上
  };
};

interface DateRangeParamWidgetValue extends ParamWidgetValue {
  value: [string, string]; // [YYYY-MM-DD, YYYY-MM-DD]
};

チェックボックス

真偽値を切り替えるフォームを表示します
escapeType: 'BOOLEAN' のプレースホルダから参照できます

interface CheckboxParamWidget extends ParamWidget {
  type: "CHECKBOX";
  settings: {
    description?: string;
  };
  defaultValue?: {
    type: "FIXED";
    fixedValue: boolean;
  };
};

interface CheckboxParamWidgetValue extends ParamWidgetValue {
  value: boolean;
};

パラメータの利用例

---
type: CODATUM_NOTEBOOK
id: 69cdbd92e8d19797ec0f51c5
name: Parameter example
notebook_param_widgets:
  - id: 69d85dbde5f3e9884e7c13ca
    type: TEXT_INPUT
    label: Text Input
    settings: {}
---

# Page1

```yaml {.page}
type: DOC_PAGE
id: 69d85db6a2dd9f8a9c982d1e
notebook_param_widget_values:
  - id: 69d85dbde5f3e9884e7c13ca
    value: 'Hello, world!'
page_param_widgets:
  - id: 69d85dc9a7430e6be6c08542
    type: NUMBER_INPUT
    label: Number Input
    settings: {}
page_param_widget_values:
  - id: 69d85dc9a7430e6be6c08542
    value: 123
```

# Parameter example

- Text Input

:::sql-block
```yaml {.attrs}
id: 69d85de3f84c5f5c340d2644
name: Text Input
bindings:
  - type: PARAM_REF
    refParamKey: 69d85dbde5f3e9884e7c13ca
    escapeType: STRING
  - type: PARAM_REF
    refParamKey: 69d85dc9a7430e6be6c08542
    escapeType: NUMBER
```

```sql
SELECT $1 as message LIMIT $2
```
:::

選択肢の生成方法

選択肢は optionsSourceType に応じて以下の方法で生成できます。

固定リスト

optionsSourceType: 'TEXT' を指定
optionsSourceText に改行区切りで選択の一覧を指定
- ラベルと値を分ける場合は、同じ行に 値,ラベル のようにカンマ区切りで指定

テーブル

DWHのテーブルのデータから選択肢を生成します
- ユーザの入力に応じて選択肢の絞り込みを行うため、指定したテーブルへのクエリが高頻度で実行されます。なるべく行数の少ないテーブルを指定してください
optionsSourceType: 'TABLE' を指定
optionsSourceTableResourceId にテーブルリソースIDを指定
optionsSourceTableValueField に値となるカラムを指定
optionsSourceTableLabelField にラベルとなるカラムを指定（未指定の場合は、値をラベルとして使用します）

クエリ実行結果

指定したSQLの実行結果から選択肢を生成します
- ユーザの入力に応じて選択肢の絞り込みを行うため、指定したSQLが高頻度で実行されます。処理に時間がかかるSQLは指定しないでください
optionsSourceType: 'SQL' を指定
optionsSourceSqlConnId には cdm connection list で確認したコネクションIDを指定します
optionsSourceSql にSQLを指定
- SQLブロックと同様のプレースホルダと参照を利用できます
- SourceSqlBinding には、パラメータ参照(type: 'PARAM_REF')とテーブル参照(type: 'TABLE_REF')を指定できます
- パラメータ参照を利用することで、他のパラメータに連動して選択肢を生成できます
  - 例: 大カテゴリのパラメータに応じて小カテゴリのパラメータの選択肢を生成する
optionsSourceSqlResetIfDependentChanged に依存パラメータ変更時に選択をリセットするかを指定（未指定の場合は、選択をリセットしません）

type SelectOptionsSettings =
  | {
      optionsSourceType: 'TEXT';
      optionsSourceText: string;
    }
  | {
      optionsSourceType: 'TABLE';
      optionsSourceTableResourceId: TableResourceId;
      optionsSourceTableValueField: string;
      optionsSourceTableLabelField?: string;
    }
  | {
      optionsSourceType: 'SQL';
      optionsSourceSqlConnId?: ObjectId;
      optionsSourceSql: string;
      optionsSourceSqlBindings?: SourceSqlBinding[];
      optionsSourceSqlResetIfDependentChanged?: boolean;
    };

type SourceSqlBinding = {
  type: 'PARAM_REF';
  refParamKey: string;
  escapeType: SQLParamEscapeType;
} | {
  type: 'TABLE_REF';
  tableResourceId: TableResourceId;
  withAlias?: boolean;
};

動的な選択肢の設定例

ノートブック共通のパラメータ「集計年」に応じて、「出発ステーション」の選択肢を動的に生成する例です（フロントマターだけ抜粋）。

optionsSourceSqlResetIfDependentChanged: true を指定することで、依存するパラメータ（この例では「集計年」）が変更された時に、「出発ステーション」の選択肢をデフォルト値にリセットします。

---
type: CODATUM_NOTEBOOK
name: パラメータ連動の例
notebook_param_widgets:
  - id: 69f402b7cfdb63ad974352c2
    type: NUMBER_SELECT
    label: 集計年
    settings:
      optionsSourceType: SQL
      optionsSourceSql: |
        SELECT DISTINCT EXTRACT(YEAR FROM start_date) AS y
        FROM `bigquery-public-data.san_francisco_bikeshare.bikeshare_trips`
        WHERE start_date IS NOT NULL
        ORDER BY y
    defaultValue:
      type: FIXED
      fixedValue: 2015
  - id: 69f402c7de82fc3714e5ed1c
    type: TEXT_SELECT
    label: 出発ステーション
    settings:
      optionsSourceType: SQL
      optionsSourceSql: |
        SELECT DISTINCT start_station_name
        FROM `bigquery-public-data.san_francisco_bikeshare.bikeshare_trips`
        WHERE start_date IS NOT NULL
          AND EXTRACT(YEAR FROM start_date) = $1
          AND start_station_name IS NOT NULL
        ORDER BY start_station_name
      optionsSourceSqlBindings:
        - type: PARAM_REF
          refParamKey: 69f402b7cfdb63ad974352c2
          escapeType: NUMBER
      optionsSourceSqlResetIfDependentChanged: true
---

パラメータ ​

概要 ​

スコープ ​

型定義 ​

パラメータの種類 ​

テキスト入力 ​

テキスト複数入力 ​

テキスト選択 ​

テキスト複数選択 ​

数値入力 ​

数値選択 ​

日付入力 ​

日付範囲 ​

チェックボックス ​

パラメータの利用例 ​

選択肢の生成方法 ​

固定リスト ​

テーブル ​

クエリ実行結果 ​

動的な選択肢の設定例 ​