# 画面設計書 220-CSVインポートエクスポート

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける「CSVインポート/エクスポート」機能（Import-DbaCsv、Export-DbaCsv）の画面設計書です。CSVファイルとSQL Serverテーブル間のデータ転送を高速かつ信頼性高く行う機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Server管理者やDBAは、ETLプロセス、データマイグレーション、レポーティング、アーカイブなど様々な場面でCSVデータの入出力を行います。Import-DbaCsvはSqlBulkCopyを使用して大容量CSVファイルを高速にインポートし、Export-DbaCsvはクエリ結果やテーブルデータを圧縮オプション付きでエクスポートします。

**画面へのアクセス方法**：PowerShellコンソールから `Import-DbaCsv` または `Export-DbaCsv` コマンドを実行します。

**主要な操作・処理内容**：
1. **Import-DbaCsv**:
   - CSVファイル（.csv、.csv.gz）を読み込む
   - SqlBulkCopyでSQL Serverテーブルにバルクインサート
   - トランザクション内で実行（ロールバック可能）
   - 自動テーブル作成、カラムマッピング対応
2. **Export-DbaCsv**:
   - SQLクエリまたはテーブルからデータを取得
   - パイプラインオブジェクトも処理可能
   - CSV形式でファイル出力
   - 圧縮オプション（GZip、Deflate、Brotli、ZLib）

**画面遷移**：CLIコマンドのため画面遷移はありません。

**権限による表示制御**：SQL Serverへの接続にはターゲットテーブルへの読み書き権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 281 | Import-DbaCsv | 主機能 | CSVインポート |
| 213 | Export-DbaCsv | 主機能 | CSVエクスポート |

## 画面種別

コマンドライン（CLI）実行画面

## URL/ルーティング

```powershell
# CSVインポート
Import-DbaCsv -Path C:\temp\data.csv -SqlInstance sql2016 -Database mydb -Table mytable

# CSVエクスポート（クエリ）
Export-DbaCsv -SqlInstance sql001 -Database Northwind -Query "SELECT * FROM Customers" -Path C:\temp\customers.csv

# CSVエクスポート（テーブル、圧縮）
Export-DbaCsv -SqlInstance sql001 -Database Northwind -Table "dbo.Orders" -Path C:\temp\orders.csv.gz -CompressionType GZip
```

## 入出力項目

### Import-DbaCsv パラメータ（主要）

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| Path | string | Yes | - | CSVファイルパス（.csv, .csv.gz対応） |
| SqlInstance | string | Yes | - | ターゲットSQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 代替認証情報 |
| Database | string | Yes | - | ターゲットデータベース |
| Schema | string | No | dbo | ターゲットスキーマ |
| Table | string | No | ファイル名 | ターゲットテーブル名 |
| Delimiter | string | No | , | フィールド区切り文字 |
| NoHeaderRow | switch | No | $false | 最初の行をデータとして扱う |
| Column | string[] | No | - | インポートするカラム |
| ColumnMap | hashtable | No | - | カラムマッピング |
| AutoCreateTable | switch | No | $false | テーブルを自動作成 |
| Truncate | switch | No | $false | インポート前にテーブルをtruncate |
| BatchSize | int | No | 50000 | バッチサイズ |
| NotifyAfter | int | No | 50000 | 進捗通知間隔 |
| TableLock | switch | No | $false | テーブルロックを取得 |
| FireTriggers | switch | No | $false | トリガーを実行 |
| KeepIdentity | switch | No | $false | ID値を保持 |
| NoTransaction | switch | No | $false | トランザクションを使用しない |

### Export-DbaCsv パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | No | - | SQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 代替認証情報 |
| Database | string | No | - | データベース |
| Query | string | No | - | T-SQLクエリ |
| Table | string | No | - | エクスポートするテーブル |
| InputObject | object[] | No | - | パイプライン入力 |
| Path | string | Yes | - | 出力ファイルパス |
| Delimiter | string | No | , | フィールド区切り文字 |
| NoHeader | switch | No | $false | ヘッダー行を出力しない |
| Quote | char | No | " | 引用符文字 |
| QuotingBehavior | string | No | AsNeeded | 引用動作（AsNeeded/Always/Never/NonNumeric） |
| Encoding | string | No | UTF8 | 文字エンコーディング |
| NullValue | string | No | 空文字 | NULL値の表現 |
| DateTimeFormat | string | No | yyyy-MM-dd HH:mm:ss.fff | 日時フォーマット |
| CompressionType | string | No | None | 圧縮タイプ（None/GZip/Deflate/Brotli/ZLib） |
| CompressionLevel | string | No | Optimal | 圧縮レベル（Fastest/Optimal/SmallestSize/NoCompression） |
| Append | switch | No | $false | 既存ファイルに追記 |
| NoClobber | switch | No | $false | 既存ファイルを上書きしない |

## 表示項目

### Import-DbaCsv 出力

コマンドは進捗情報を表示しますが、明示的な出力オブジェクトはありません。

### Export-DbaCsv 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| Path | string | 出力ファイルパス |
| RowsExported | int | エクスポートされた行数 |
| FileSizeBytes | long | ファイルサイズ（バイト） |
| FileSizeMB | double | ファイルサイズ（MB） |
| CompressionType | string | 圧縮タイプ |
| Elapsed | TimeSpan | 処理時間 |
| RowsPerSecond | double | 秒あたりの行数 |

## イベント仕様

### 1-Import-DbaCsv実行時

1. CSVファイルを読み込む（.gz対応、自動解凍）
2. SQL Serverに接続
3. トランザクション開始（NoTransactionでない場合）
4. Truncate指定時はテーブルをtruncate
5. AutoCreateTable指定時はテーブルを作成
6. SqlBulkCopyでデータをインサート
7. NotifyAfter行ごとに進捗を通知
8. トランザクションをコミット（または失敗時ロールバック）

### 2-Export-DbaCsv実行時

1. パラメータ検証（SqlInstance時はQuery/Tableが必要）
2. ファイル拡張子から圧縮タイプを自動検出（未指定時）
3. CsvWriterOptionsを設定
4. SQL Serverに接続（SqlInstance指定時）
5. クエリ実行またはテーブル読み込み
6. CsvWriterでファイル出力（圧縮オプション適用）
7. 結果オブジェクトを出力

## データベース更新仕様

### Import-DbaCsv

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| AutoCreateTable | 指定テーブル | CREATE | テーブル自動作成 |
| Truncate | 指定テーブル | TRUNCATE | データ削除 |
| インポート | 指定テーブル | INSERT | バルクインサート |

### Export-DbaCsv

データベースを更新しません。読み取りのみ。

## メッセージ仕様

| 種別 | メッセージ | 発生条件 |
|------|----------|---------|
| エラー | When using -SqlInstance, you must specify either -Query or -Table | SqlInstance時にQuery/Tableなし |
| エラー | You cannot specify both -Query and -Table | Query と Table を両方指定 |
| エラー | When using -SqlInstance with -Query or -Table, you must specify -Database | Database未指定 |
| エラー | File '{Path}' already exists and -NoClobber was specified | ファイル存在時にNoClobber |
| 警告 | CompressionLevel 'SmallestSize' is not available in Windows PowerShell | Windows PowerShellでSmallestSize |
| Verbose | Executing query on {instance} | クエリ実行時 |

## 例外処理

| 例外条件 | 動作 |
|---------|------|
| 接続エラー | Stop-Functionでエラーを報告し、次のインスタンスに継続 |
| パラメータ不正 | Stop-Functionで処理を中断 |
| ファイル存在（NoClobber） | Stop-Functionで処理を中断 |
| エクスポートエラー | Stop-Functionでエラーを報告 |

## 備考

- Import-DbaCsvはSqlBulkCopyを使用して高速インポート
- トランザクション内で実行されるため、失敗時は自動ロールバック
- .csv.gzファイルは自動的に解凍される
- Export-DbaCsvはファイル拡張子から圧縮タイプを自動検出
- Brotli、ZLibは.NET 8+のみサポート
- SmallestSizeはWindows PowerShellでは使用不可（Optimalにフォールバック）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaCsv.ps1 | `public/Export-DbaCsv.ps1` | 出力オブジェクトの構造（行111-124, 392-400） |

**読解のコツ**: Export-DbaCsvはエクスポート結果のサマリー情報を返します。Import-DbaCsvは明示的な出力オブジェクトがありません。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Import-DbaCsv.ps1 | `public/Import-DbaCsv.ps1` | パラメータ定義（行15-200以降）とSqlBulkCopy処理 |
| 2-2 | Export-DbaCsv.ps1 | `public/Export-DbaCsv.ps1` | パラメータ定義（行165-192）とCsvWriter処理 |

**主要処理フロー (Export-DbaCsv)**:
1. **行194-265**: beginブロックでパラメータ検証とCsvWriterOptions設定
2. **行211-220**: ファイル拡張子から圧縮タイプを自動検出
3. **行267-333**: processブロックでSQLクエリ実行
4. **行336-401**: endブロックでInputObject処理と結果出力

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

```
Import-DbaCsv
    |
    +-- CSVファイル読み込み
    |      +-- .csv.gz自動解凍
    |
    +-- Connect-DbaInstance
    |      +-- SQL Server接続
    |
    +-- トランザクション管理
    |      +-- SqlTransaction
    |
    +-- SqlBulkCopy
    |      +-- バルクインサート
    |
    +-- 進捗通知
           +-- NotifyAfter行ごと

Export-DbaCsv
    |
    +-- パラメータ検証
    |      +-- SqlInstance/Query/Table整合性
    |
    +-- 圧縮タイプ自動検出
    |      +-- ファイル拡張子から判定
    |
    +-- CsvWriterOptions設定
    |      +-- Delimiter, Quote, Encoding等
    |
    +-- Connect-DbaInstance（SqlInstance時）
    |
    +-- クエリ実行/データ取得
    |      +-- ExecuteReader
    |
    +-- CsvWriter
    |      +-- WriteFromReader/WriteRow
    |
    +-- 結果オブジェクト生成
```

### データフロー図

```
[Import-DbaCsv]

CSVファイル ─────────▶ CSV Reader ────────────────▶ データ行
      |
      v
                    SqlBulkCopy ──────────────────▶ SQL Serverテーブル
      |
      v
トランザクション ────▶ コミット/ロールバック ────▶ 処理完了

[Export-DbaCsv]

SqlInstance/Query ───▶ ExecuteReader ─────────────▶ DataReader
      |
      v
InputObject ─────────▶ オブジェクト配列
      |
      v
                    CsvWriter ────────────────────▶ CSVファイル
      |                  |
      |                  +── 圧縮オプション適用
      v
                    結果オブジェクト生成 ─────────▶ 出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Import-DbaCsv.ps1 | `public/Import-DbaCsv.ps1` | ソース | CSVインポートコマンド |
| Export-DbaCsv.ps1 | `public/Export-DbaCsv.ps1` | ソース | CSVエクスポートコマンド |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |

### サポートされる圧縮タイプ

| 圧縮タイプ | 拡張子 | .NET要件 |
|-----------|--------|----------|
| None | .csv | - |
| GZip | .gz | - |
| Deflate | .deflate | - |
| Brotli | .br | .NET 8+ |
| ZLib | .zlib | .NET 8+ |
