# 機能設計書 141-Get-DbaRandomizedDataset

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`Get-DbaRandomizedDataset`コマンドレットの機能設計を定義する。本機能は、定義済みテンプレートを使用してランダムなテストデータを生成し、開発・テスト環境向けの現実的なサンプルデータを作成する。

### 本機能の処理概要

`Get-DbaRandomizedDataset`は、JSONテンプレートに基づいてランダムなテストデータセットを生成するコマンドレットである。テンプレートは列名とデータ型を定義し、SQL Serverデータ型（varchar、int、datetime）またはセマンティックデータ型（Name.FirstName、Address.City、Person.DateOfBirth）を指定することで、より現実的なデータセットを作成できる。

**業務上の目的・背景**：データベース開発やテストでは、本番データを使用せずに現実的なテストデータが必要となる場面が多い。個人情報保護の観点から本番データの使用が制限される環境や、新規開発でデータが存在しない場合に、本機能を使用することで迅速にテストデータを準備できる。また、データマスキングやパフォーマンステストの前提データ作成にも活用される。

**機能の利用シーン**：
- 開発環境でのデータベーステスト用サンプルデータ作成
- QA環境でのテストデータセット生成
- データマスキング機能のテスト
- デモ環境向けダミーデータ準備
- パフォーマンステスト用の大量データ生成

**主要な処理内容**：
1. テンプレート名または直接テンプレートファイルパスからテンプレート情報を取得
2. テンプレートJSONファイルを解析し、列定義（Name、Type、SubType）を抽出
3. 指定行数分のループを実行し、各列に対してGet-DbaRandomizedValueを呼び出して値を生成
4. PSCustomObjectとして行データを構築し、パイプラインに出力

**関連システム・外部連携**：
- Bogusライブラリ（内部で使用されるフェイクデータ生成ライブラリ）
- Get-DbaRandomizedDatasetTemplate（テンプレート取得）
- Get-DbaRandomizedValue（個別値生成）

**権限による制御**：本機能は純粋なデータ生成機能であり、SQL Serverへの接続や特別な権限は不要である。ローカルファイルシステムへのアクセス権限のみが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主機能 | テストデータ生成 |

## 機能種別

データ生成処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Template | string[] | No | 使用する組み込みテンプレート名 | bin\randomizer\templates配下に存在すること |
| TemplateFile | string[] | No | カスタムJSONテンプレートファイルパス | 有効なJSONファイルであること |
| Rows | int | No | 生成する行数（デフォルト100） | 正の整数 |
| Locale | string | No | ロケール設定（デフォルト'en'） | 有効なロケールコード |
| InputObject | object[] | No | パイプライン入力（テンプレートオブジェクト） | Get-DbaRandomizedDatasetTemplateからの出力 |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- テンプレートJSONファイル（組み込みまたはカスタム）
- パイプライン入力（Get-DbaRandomizedDatasetTemplateからの出力）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| （動的プロパティ） | object | テンプレートのColumns定義に基づく動的プロパティ |

### 出力先

パイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   └─ Template、TemplateFile、InputObjectのいずれかが指定されていることを確認
2. テンプレート取得
   └─ Templateが指定された場合、Get-DbaRandomizedDatasetTemplateを呼び出し
3. テンプレート解析ループ
   └─ 各テンプレートファイルに対して処理を実行
4. JSONパース
   └─ テンプレートファイルをGet-ContentとConvertFrom-Jsonで解析
5. 行生成ループ（1〜Rows回）
   └─ 新規PSCustomObjectを作成
6. 列データ生成ループ（各Column）
   ├─ SubTypeがサポートデータ型の場合：Get-DbaRandomizedValue -DataType
   └─ それ以外の場合：Get-DbaRandomizedValue -RandomizerType -RandomizerSubtype
7. プロパティ追加
   └─ Add-Memberで生成値をオブジェクトに追加
8. 出力
   └─ PSCustomObjectをパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Template/TemplateFile/InputObject<br/>いずれか指定あり?}
    B -->|No| C[エラー: テンプレート指定必須]
    B -->|Yes| D{Templateパラメータ<br/>指定あり?}
    D -->|Yes| E[Get-DbaRandomizedDatasetTemplate<br/>でテンプレート取得]
    D -->|No| F[InputObject/TemplateFile<br/>をそのまま使用]
    E --> G[テンプレートファイル<br/>ループ開始]
    F --> G
    G --> H[JSONファイル読み込み<br/>ConvertFrom-Json]
    H --> I{パース成功?}
    I -->|No| J[エラー: テンプレート解析失敗]
    I -->|Yes| K[行ループ開始<br/>i = 1 to Rows]
    K --> L[新規PSCustomObject作成]
    L --> M[列ループ開始]
    M --> N{SubTypeが<br/>サポートデータ型?}
    N -->|Yes| O[Get-DbaRandomizedValue<br/>-DataType]
    N -->|No| P[Get-DbaRandomizedValue<br/>-RandomizerType -RandomizerSubtype]
    O --> Q[Add-Memberで値追加]
    P --> Q
    Q --> R{全列処理完了?}
    R -->|No| M
    R -->|Yes| S[PSCustomObject出力]
    S --> T{全行処理完了?}
    T -->|No| K
    T -->|Yes| U{全テンプレート<br/>処理完了?}
    U -->|No| G
    U -->|Yes| V[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | テンプレート必須 | Template、TemplateFile、InputObjectのいずれかが必須 | 常時 |
| BR-002 | データ型判定 | SubTypeがサポートデータ型リストに含まれる場合はDataTypeとして処理 | 列処理時 |
| BR-003 | デフォルト行数 | Rows未指定時は100行を生成 | Rows未指定時 |
| BR-004 | デフォルトロケール | Locale未指定時は'en'を使用 | Locale未指定時 |

### 計算ロジック

特になし（ランダム値生成はGet-DbaRandomizedValueに委譲）

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベースへのアクセスを行わない。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベースアクセスなし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 入力検証エラー | Template/TemplateFile/InputObjectがすべて未指定 | 適切なパラメータを指定 |
| - | テンプレート未発見 | 指定テンプレートが見つからない | テンプレート名を確認 |
| - | JSONパースエラー | テンプレートファイルのJSON形式が不正 | テンプレートファイルを修正 |
| - | 値生成エラー | Get-DbaRandomizedValueで値生成失敗 | テンプレートのType/SubType定義を確認 |

### リトライ仕様

リトライは実装されていない。エラー発生時はStop-Functionで処理を中断。

## トランザクション仕様

データベーストランザクションは使用しない。

## パフォーマンス要件

- 大量行（数万行以上）の生成時はメモリ使用量に注意
- 各行は即座にパイプラインに出力されるため、メモリ効率は良好

## セキュリティ考慮事項

- 生成されるデータはフェイクデータであり、実在する個人情報ではない
- カスタムテンプレートファイルへのアクセス権限はOSレベルで制御

## 備考

- サポートされるデータ型: bigint, bit, bool, char, date, datetime, datetime2, decimal, int, float, guid, money, numeric, nchar, ntext, nvarchar, real, smalldatetime, smallint, text, time, tinyint, uniqueidentifier, userdefineddatatype, varchar
- 組み込みテンプレートはモジュールのbin\randomizer\templatesディレクトリに配置

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

テンプレートJSONファイルの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | PersonalData.json（例） | `bin/randomizer/templates/*.json` | Columns配列、Name/Type/SubTypeプロパティの構造 |

**読解のコツ**: テンプレートJSONはColumns配列を持ち、各要素がName（列名）、Type（ランダマイザータイプ）、SubType（サブタイプ）を定義する。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaRandomizedDataset.ps1 | `public/Get-DbaRandomizedDataset.ps1` | メイン処理フロー |

**主要処理フロー**:
1. **119-127行目**: 入力検証とテンプレート取得
2. **129-140行目**: Templateパラメータ指定時のテンプレート取得処理
3. **142-149行目**: テンプレートファイルのJSON解析
4. **152-171行目**: 行ループと列データ生成
5. **157-161行目**: データ型判定とGet-DbaRandomizedValue呼び出し
6. **163行目**: Add-Memberによるプロパティ追加
7. **169行目**: オブジェクトのパイプライン出力

#### Step 3: 依存機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaRandomizedDatasetTemplate.ps1 | `public/Get-DbaRandomizedDatasetTemplate.ps1` | テンプレート検索ロジック |
| 3-2 | Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | 値生成ロジック |

**主要処理フロー**:
- **Get-DbaRandomizedDatasetTemplate 86行目**: デフォルトテンプレートディレクトリからの取得
- **Get-DbaRandomizedValue 186-189行目**: Bogus Fakerオブジェクトの初期化

### プログラム呼び出し階層図

```
Get-DbaRandomizedDataset
    │
    ├─ Get-DbaRandomizedDatasetTemplate（Templateパラメータ指定時）
    │      └─ Get-ChildItem（テンプレートファイル検索）
    │
    ├─ Get-Content（テンプレートファイル読み込み）
    │      └─ ConvertFrom-Json（JSON解析）
    │
    └─ Get-DbaRandomizedValue（各列の値生成）
           └─ Bogus.Faker（フェイクデータ生成ライブラリ）
```

### データフロー図

```
[入力]               [処理]                    [出力]

Template名 ───▶ Get-DbaRandomizedDatasetTemplate ─┐
                                                  │
TemplateFile ─────────────────────────────────────┤
                                                  ▼
                      テンプレートJSONファイル
                              │
                              ▼
                      ConvertFrom-Json
                              │
                              ▼
                      Columns配列取得
                              │
                     ┌────────┴────────┐
                     ▼                  ▼
              DataType判定        RandomizerType判定
                     │                  │
                     └────────┬─────────┘
                              ▼
                    Get-DbaRandomizedValue
                              │
                              ▼
                      PSCustomObject ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaRandomizedDataset.ps1 | `public/Get-DbaRandomizedDataset.ps1` | ソース | メイン機能 |
| Get-DbaRandomizedDatasetTemplate.ps1 | `public/Get-DbaRandomizedDatasetTemplate.ps1` | ソース | テンプレート取得 |
| Get-DbaRandomizedValue.ps1 | `public/Get-DbaRandomizedValue.ps1` | ソース | 値生成 |
| *.json | `bin/randomizer/templates/` | テンプレート | データ生成テンプレート定義 |
| en.randomizertypes.csv | `bin/randomizer/en.randomizertypes.csv` | データ | ランダマイザータイプ定義 |
