# 帳票設計書 1-Export-DbaCsv

## 概要

本ドキュメントは、dbatools PowerShellモジュールのExport-DbaCsvコマンドレットに関する帳票設計書です。SQLクエリ結果またはテーブルデータを圧縮オプション付きでCSVファイルにエクスポートする機能について記載しています。

### 本帳票の処理概要

Export-DbaCsvは、SQL Serverからデータを取得し、高性能なCSVエクスポート機能を提供するコマンドレットです。GZip、Deflate、Brotli、ZLibなど複数の圧縮形式に対応し、SQLクエリ、テーブル、またはパイプラインで渡されたオブジェクトからデータをCSVファイルに出力できます。

**業務上の目的・背景**：大量のデータをSQL Serverから外部システムへ移行する場合や、定期的なデータエクスポート処理において、ファイルサイズの削減と転送効率の向上が求められます。本帳票は、ETLプロセス、データエクスポート、レポーティング、およびSQL Serverからのポータブルなデータファイル作成に最適なソリューションを提供します。

**帳票の利用シーン**：
1. データウェアハウスへのデータ移行時のステージングファイル作成
2. 定期的なバックアップデータのアーカイブ（圧縮形式）
3. 外部システムとのデータ連携用CSVファイル生成
4. データ分析ツールへのインポート用データ準備

**主要な出力内容**：
1. CSVファイル（カンマ区切り、タブ区切り、パイプ区切り等カスタマイズ可能）
2. 圧縮CSVファイル（.gz、.br、.deflate、.zlib拡張子）
3. エクスポートサマリー情報（行数、ファイルサイズ、処理時間等）

**帳票の出力タイミング**：PowerShellコンソールまたはスクリプトからExport-DbaCsvコマンドを実行した時点で即座にファイルが生成されます。

**帳票の利用者**：データベース管理者（DBA）、データエンジニア、システム管理者、ETL開発者

## 帳票種別

データエクスポートファイル（CSV / 圧縮CSV）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | PowerShellコンソール | N/A | Export-DbaCsvコマンド実行 |
| N/A | PowerShell ISE | N/A | スクリプト実行 |
| N/A | VS Code Terminal | N/A | スクリプト実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | CSV / 圧縮CSV（GZip/Deflate/Brotli/ZLib） |
| 用紙サイズ | N/A（データファイル） |
| 向き | N/A |
| ファイル名 | -Pathパラメータで指定（例: customers.csv, data.csv.gz） |
| 出力方法 | ファイル書き込み |
| 文字コード | UTF8（デフォルト）/ ASCII / BigEndianUnicode / Unicode / UTF7 / UTF32 |

### CSV固有設定

| 項目 | 内容 |
|-----|------|
| 区切り文字 | カンマ（デフォルト）、タブ、パイプ、セミコロン等カスタマイズ可能 |
| 引用符 | ダブルクォート（デフォルト） |
| 引用動作 | AsNeeded / Always / Never / NonNumeric |
| NULL値表現 | 空文字（デフォルト）またはカスタム文字列 |
| 日時形式 | yyyy-MM-dd HH:mm:ss.fff（ISO 8601、デフォルト） |

### 圧縮固有設定

| 項目 | 内容 |
|-----|------|
| 圧縮タイプ | None / GZip / Deflate / Brotli / ZLib |
| 圧縮レベル | Fastest / Optimal / SmallestSize / NoCompression |
| 自動検出 | ファイル拡張子から圧縮タイプを自動判定 |

## 帳票レイアウト

### レイアウト概要

CSVファイルは標準的な表形式データ構造で出力されます。

```
┌─────────────────────────────────────┐
│         ヘッダー行（列名）            │
├─────────────────────────────────────┤
│           データ行1                 │
│           データ行2                 │
│           データ行3                 │
│             ...                    │
│           データ行N                 │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | 列名1 | データソースの最初の列名 | クエリ結果/テーブル定義 | 文字列 |
| 2 | 列名2 | データソースの2番目の列名 | クエリ結果/テーブル定義 | 文字列 |
| N | 列名N | データソースのN番目の列名 | クエリ結果/テーブル定義 | 文字列 |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | データ値1 | 各行の1列目のデータ値 | SQLクエリ結果 | データ型に応じた形式 | 可変 |
| 2 | データ値2 | 各行の2列目のデータ値 | SQLクエリ結果 | データ型に応じた形式 | 可変 |
| N | データ値N | 各行のN列目のデータ値 | SQLクエリ結果 | データ型に応じた形式 | 可変 |

### フッター部

CSVファイルにはフッター部はありません。ただし、コマンド実行後にエクスポートサマリーオブジェクトが返されます。

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Path | 出力ファイルの完全パス | 処理結果 | 文字列 |
| 2 | RowsExported | エクスポートされた行数 | 処理結果 | 整数 |
| 3 | FileSizeBytes | ファイルサイズ（バイト） | ファイル情報 | 整数 |
| 4 | FileSizeMB | ファイルサイズ（MB） | 計算値 | 小数点2桁 |
| 5 | CompressionType | 使用した圧縮タイプ | パラメータ | 文字列 |
| 6 | Elapsed | 処理時間 | Stopwatch | TimeSpan |
| 7 | RowsPerSecond | 1秒あたりの行数 | 計算値 | 小数点1桁 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| SqlInstance | 対象SQL Serverインスタンス | Yes（パイプライン入力時はNo） |
| Database | 対象データベース名 | Yes（Query/Table使用時） |
| Query | 実行するT-SQLクエリ | QueryまたはTableのいずれか |
| Table | エクスポート対象テーブル名 | QueryまたはTableのいずれか |
| Path | 出力ファイルパス | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | クエリ結果の順序に依存 | N/A |

### 改ページ条件

CSVファイルのため改ページは適用されません。

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| -Queryパラメータで指定 | SQLクエリの実行対象 | クエリ内で定義 |
| -Tableパラメータで指定 | テーブルデータの取得対象 | なし |

### テーブル別参照項目詳細

#### 動的参照

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| * | CSV列として出力 | クエリで定義 | クエリ結果の全列が対象 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| FileSizeMB | FileSizeBytes / 1MB | Round(2) | MB単位に変換 |
| RowsPerSecond | RowsExported / Elapsed.TotalSeconds | Round(1) | スループット計算 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Export-DbaCsv実行] --> B[パラメータ検証]
    B --> C{入力ソース判定}
    C -->|SqlInstance| D[SQL Server接続]
    C -->|InputObject| E[パイプラインオブジェクト収集]
    D --> F[クエリ/テーブルデータ取得]
    F --> G[CsvWriterOptions設定]
    E --> G
    G --> H[CsvWriter初期化]
    H --> I{データ書き込み}
    I -->|DataReader| J[WriteFromReader]
    I -->|Objects| K[WriteRow]
    J --> L[ファイルクローズ]
    K --> L
    L --> M[サマリーオブジェクト生成]
    M --> N[結果出力]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| パラメータエラー | SqlInstance使用時にQuery/Tableが未指定 | "When using -SqlInstance, you must specify either -Query or -Table to define what data to export" | -Queryまたは-Tableを指定 |
| パラメータエラー | QueryとTableを同時に指定 | "You cannot specify both -Query and -Table. Please use one or the other" | いずれか一方のみ指定 |
| パラメータエラー | SqlInstance使用時にDatabaseが未指定 | "When using -SqlInstance with -Query or -Table, you must specify -Database" | -Databaseを指定 |
| ファイル存在エラー | NoClobber指定時にファイルが既存 | "File 'path' already exists and -NoClobber was specified" | 別のファイル名を使用またはNoClobberを外す |
| 接続エラー | SQL Server接続失敗 | "Failed to connect to instance" | 接続情報を確認 |
| エクスポートエラー | データエクスポート失敗 | "Failed to export data from instance" | クエリやテーブル名を確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 数百万行規模 |
| 目標出力時間 | データ量に依存（RowsPerSecondで確認可能） |
| 同時出力数上限 | 1セッション1ファイル |

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

- SQL Server認証情報はSecureString（PSCredential）で管理される
- データベース接続にはWindows認証またはSQL認証が使用可能
- 出力ファイルにはアクセス権限制御が必要な場合あり
- 機密データを含む場合は出力先の暗号化を検討

## 備考

- .NET 8以降でのみBrotli、ZLib圧縮が利用可能
- SmallestSize圧縮レベルはWindows PowerShell（.NET Framework）では非対応
- ファイル拡張子から圧縮タイプを自動検出する機能あり
- Appendモード使用時はヘッダーが自動的に抑制される

---

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

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

### 推奨読解順序

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

CsvWriterOptionsクラスとCsvWriterクラスがデータ処理の中心となります。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CsvWriterOptions.cs | `src/Dataplat.Dbatools.Csv/Writer/CsvWriterOptions.cs`（推定） | CSVエクスポートオプションの構造を理解 |
| 1-2 | CsvWriter.cs | `src/Dataplat.Dbatools.Csv/Writer/CsvWriter.cs`（推定） | CSV書き込み処理の実装を理解 |
| 1-3 | CompressionType.cs | `src/Dataplat.Dbatools.Csv/Compression/CompressionType.cs`（推定） | 圧縮タイプの列挙を理解 |

**読解のコツ**: C#のenumやclassとPowerShellの型変換を確認すること

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

PowerShellコマンドレットとしてのExport-DbaCsv.ps1がエントリーポイントです。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaCsv.ps1 | `public/Export-DbaCsv.ps1` | コマンドレットのパラメータ定義と処理フロー |

**主要処理フロー**:
1. **行194-265**: beginブロック - パラメータ検証、圧縮タイプの自動検出、WriterOptions初期化
2. **行267-333**: processブロック - SQL Server接続、クエリ実行、データ書き込み
3. **行336-402**: endブロック - パイプラインオブジェクト処理、サマリー出力

#### Step 3: パラメータ検証処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaCsv.ps1 | `public/Export-DbaCsv.ps1` | beginブロックのパラメータ検証ロジック |

**主要処理フロー**:
- **行196-209**: SqlInstance使用時の必須パラメータチェック
- **行212-219**: ファイル拡張子からの圧縮タイプ自動検出
- **行223-226**: NoClobber時のファイル存在チェック

#### Step 4: データエクスポート処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbaCsv.ps1 | `public/Export-DbaCsv.ps1` | processブロックのデータ取得と書き込み |

**主要処理フロー**:
- **行279-284**: SQL Server接続（Connect-DbaInstance使用）
- **行286-300**: クエリまたはテーブル名からSQLを構築
- **行316-327**: DataReaderを使用したデータ書き込み

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

```
Export-DbaCsv (PowerShell)
    │
    ├─ Test-Bound (dbatools内部関数)
    │      └─ パラメータバインド確認
    │
    ├─ Stop-Function (dbatools内部関数)
    │      └─ エラー処理とメッセージ出力
    │
    ├─ Connect-DbaInstance (dbatools関数)
    │      └─ SQL Server接続管理
    │
    ├─ Write-Message (dbatools内部関数)
    │      └─ ログ/メッセージ出力
    │
    └─ Dataplat.Dbatools.Csv.Writer.CsvWriter (.NET)
           ├─ CsvWriterOptions (設定)
           ├─ WriteFromReader (DataReader処理)
           ├─ WriteHeader (ヘッダー出力)
           ├─ WriteRow (行出力)
           └─ Dispose (リソース解放)
```

### データフロー図

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

SQL Server              ┌─────────────────┐
  └─ Query/Table ──────▶│ ExecuteReader   │
                        │    (ADO.NET)    │
                        └────────┬────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │   CsvWriter     │
                        │ WriteFromReader │
                        └────────┬────────┘
                                 │                    CSVファイル
                                 ├────────────────▶ (.csv/.gz/.br)
                                 │
                                 ▼
PowerShell Objects      ┌─────────────────┐          サマリー
  └─ InputObject ──────▶│   CsvWriter     │────────▶ オブジェクト
                        │    WriteRow     │         (PSCustomObject)
                        └─────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaCsv.ps1 | `public/Export-DbaCsv.ps1` | ソース | メインコマンドレット実装 |
| CsvWriter.cs | `src/Dataplat.Dbatools.Csv/Writer/CsvWriter.cs`（推定） | ソース | CSVファイル書き込みクラス |
| CsvWriterOptions.cs | `src/Dataplat.Dbatools.Csv/Writer/CsvWriterOptions.cs`（推定） | ソース | CSV出力オプション定義 |
| CompressionType.cs | `src/Dataplat.Dbatools.Csv/Compression/CompressionType.cs`（推定） | ソース | 圧縮タイプ列挙 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続管理 |
| dbatools.psd1 | `dbatools.psd1` | 設定 | モジュールマニフェスト |
| dbatools.psm1 | `dbatools.psm1` | ソース | モジュールローダー |
