# 画面設計書 256-TempDB使用量

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Get-DbaTempdbUsage` コマンドに関する画面設計書です。このコマンドは、実行中のクエリによるTempDB使用状況を取得します。

### 本画面の処理概要

**業務上の目的・背景**：TempDBはSQL Serverのシステムデータベースとして、一時テーブル、テーブル変数、カーソル、ソート操作、ハッシュ結合などの一時的なデータ格納に使用されます。TempDBの過剰な使用は、ディスクI/Oの増加、パフォーマンス低下、最悪の場合はTempDB領域不足によるクエリ失敗を引き起こします。このコマンドは、どのセッションがTempDBを消費しているかをリアルタイムで特定し、問題のあるクエリを迅速に発見するのに役立ちます。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから `Get-DbaTempdbUsage` コマンドを実行します。SQL Serverインスタンスをパイプラインで渡すことも可能です。

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスへの接続を確立（MinimumVersion 10）
2. DMVを使用してTempDB使用状況を取得
   - sys.dm_db_session_space_usage
   - sys.dm_exec_sessions
   - sys.dm_exec_requests
   - sys.dm_db_task_space_usage
3. 割り当て/解放されたスペースがあるセッションのみを返す
4. 結果をパイプラインに出力

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

**権限による表示制御**：VIEW SERVER STATE権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 149 | Get-DbaTempdbUsage | 主機能 | TempDB使用状況の取得 |
| 162 | Get-DbaProcess | 関連機能 | 関連するプロセス情報の取得 |
| 180 | Invoke-DbaQuery | 関連機能 | 問題クエリの詳細調査 |

## 画面種別

監視・診断（CLIコマンド）

## URL/ルーティング

該当なし（PowerShell CLIコマンド）

## 入出力項目

### 入力パラメーター

| パラメーター名 | 型 | 必須 | 説明 |
|---------------|---|-----|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス名（パイプライン入力対応） |
| SqlCredential | PSCredential | No | 代替認証情報 |
| EnableException | switch | No | 例外を直接スローするかどうか |

### 出力項目

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | SQL Serverインスタンスのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Spid | int | セッションID |
| StatementCommand | string | 実行中のSQLコマンド（SELECT, INSERT, UPDATE, DELETE等） |
| QueryText | string | 実行中のT-SQLステートメントテキスト |
| ProcedureName | string | 該当する場合、ストアドプロシージャのスキーマ修飾名 |
| StartTime | datetime | リクエスト開始時刻 |
| CurrentUserAllocatedKB | int | 現在のユーザーオブジェクト割り当て（KB） |
| TotalUserAllocatedKB | int | ユーザーオブジェクト合計割り当て（KB） |
| UserDeallocatedKB | int | ユーザーオブジェクト解放（KB） |
| TotalUserDeallocatedKB | int | ユーザーオブジェクト合計解放（KB） |
| InternalAllocatedKB | int | 内部オブジェクト割り当て（KB） |
| TotalInternalAllocatedKB | int | 内部オブジェクト合計割り当て（KB） |
| InternalDeallocatedKB | int | 内部オブジェクト解放（KB） |
| TotalInternalDeallocatedKB | int | 内部オブジェクト合計解放（KB） |
| RequestedReads | int | リクエストによる物理読み取り数 |
| RequestedWrites | int | リクエストによる書き込み数 |
| RequestedLogicalReads | int | リクエストによる論理読み取り数 |
| RequestedCPUTime | int | リクエストによるCPU時間（ミリ秒） |
| IsUserProcess | bool | ユーザープロセス（true）かシステムプロセス（false） |
| Status | string | セッションの現在の状態（running, sleeping等） |
| Database | string | アクセス中のデータベース名 |
| LoginName | string | SQL Serverログイン名 |
| OriginalLoginName | string | 偽装前の元のログイン名 |
| NTDomain | string | Windows認証使用時のドメイン名 |
| NTUserName | string | Windows認証使用時のユーザー名 |
| HostName | string | クライアントコンピューターのホスト名 |
| ProgramName | string | クライアントアプリケーション名 |
| LoginTime | datetime | セッションのログイン時刻 |
| LastRequestedStartTime | datetime | 最後のリクエスト開始時刻 |
| LastRequestedEndTime | datetime | 最後のリクエスト終了時刻 |

## 表示項目

CLIコマンドのため、表示項目は出力オブジェクトのプロパティに依存します。

## イベント仕様

### 1-コマンド実行

コマンド実行時に以下の処理が行われます：

1. `Connect-DbaInstance` でSQL Server 2008以上に接続
2. 複数のDMVを結合したSQLクエリを実行
3. TempDB割り当て/解放のあるセッションのみをフィルタリング
4. 結果を直接パイプラインに出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| コマンド実行 | sys.dm_db_session_space_usage | SELECT | セッションスペース使用状況 |
| コマンド実行 | sys.dm_exec_sessions | SELECT | セッション情報 |
| コマンド実行 | sys.dm_exec_requests | SELECT | リクエスト情報 |
| コマンド実行 | sys.dm_db_task_space_usage | SELECT | タスクスペース使用状況 |
| コマンド実行 | sys.dm_exec_sql_text | SELECT | SQLテキスト |

### テーブル別更新項目詳細

このコマンドは読み取り専用であり、データベースの更新は行いません。

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|---------------|
| エラー | 接続失敗時 | "Failure" + ConnectionError詳細 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionで処理を中断して次のインスタンスへ続行 |
| SQL Server 2008未満 | Connect-DbaInstanceのMinimumVersion制約により接続失敗 |

## 備考

- SQL Server 2008（バージョン10）以上が必要
- クエリにはOPTION (RECOMPILE)ヒントが含まれ、毎回最新のプランを使用
- 自身のセッション（@@SPID）は結果から除外
- TempDB割り当て/解放が0のセッションは結果から除外
- WhatIfパラメーターが定義されているが、このコマンドは読み取り専用のため影響なし

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaTempdbUsage.ps1 | `public/Get-DbaTempdbUsage.ps1` | SQLクエリ構造（行101-156） |
| 1-2 | Get-DbaTempdbUsage.ps1 | `public/Get-DbaTempdbUsage.ps1` | 出力プロパティ（SELECTリスト） |

**読解のコツ**: このコマンドはクエリ結果を直接返すため、SQLのSELECTリストの列名がそのまま出力プロパティになります。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaTempdbUsage.ps1 | `public/Get-DbaTempdbUsage.ps1` | 関数定義全体（行1-161） |

**主要処理フロー**:
1. **行93-99**: processブロックでSQL Server 2008+に接続
2. **行101-156**: SQLクエリ構築（DMV結合とフィルタリング）
3. **行158**: クエリ実行と結果出力

#### Step 3: SQLクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaTempdbUsage.ps1 | `public/Get-DbaTempdbUsage.ps1` | DMV結合ロジック（行138-153） |
| 3-2 | Get-DbaTempdbUsage.ps1 | `public/Get-DbaTempdbUsage.ps1` | WHERE句フィルタリング（行154-155） |

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

```
Get-DbaTempdbUsage
    │
    ├─ Connect-DbaInstance (MinimumVersion 10)
    │
    └─ $server.Query($sql)
           └─ sys.dm_db_session_space_usage
                  INNER JOIN sys.dm_exec_sessions
                  LEFT JOIN sys.dm_exec_requests
                  LEFT JOIN (サブクエリ)
                      └─ sys.dm_db_task_space_usage
                  OUTER APPLY sys.dm_exec_sql_text
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server
                           │
                           ▼
                    $server.Query($sql)
                           │
                           ▼
                    DMV結合クエリ実行
                    ├─ dm_db_session_space_usage
                    ├─ dm_exec_sessions
                    ├─ dm_exec_requests
                    ├─ dm_db_task_space_usage
                    └─ dm_exec_sql_text
                           │
                           ▼
                    フィルタリング
                    ├─ session_id != @@SPID
                    └─ 割り当て/解放 != 0
                           │
                           ▼
                      DataRow ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaTempdbUsage.ps1 | `public/Get-DbaTempdbUsage.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `internal/functions/flowcontrol/Stop-Function.ps1` | ソース | エラーハンドリング |
