# 画面設計書 262-インデックスヘルプ

## 概要

本ドキュメントは、dbatoolsのインデックス情報取得機能に関する画面設計書です。SQL Serverデータベースのインデックスと統計情報を包括的に取得し、パフォーマンス分析とインデックス最適化に活用するためのPowerShellコマンドを定義します。

### 本画面の処理概要

本機能は、SQL ServerのDMV（動的管理ビュー）を使用してインデックスと統計情報の詳細データを取得し、パフォーマンス分析、インデックスメンテナンス計画、最適化機会の特定に活用するGet-DbaHelpIndexコマンドを提供します。

**業務上の目的・背景**：データベースのパフォーマンスチューニングにおいて、インデックスの構造、使用状況、断片化レベルを正確に把握することは不可欠です。本機能は、未使用インデックスの特定と削除候補の抽出、ストレージを消費している大きなインデックスの発見、メンテナンスが必要な断片化したインデックスの検出を支援します。構造情報（キー列、インクルード列、フィルター）とランタイムメトリクス（読み取り数、更新数、最終使用日時）を組み合わせて、完全なインデックスヘルス状態を把握できます。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスします。
```powershell
Get-DbaHelpIndex -SqlInstance <インスタンス名> -Database <データベース名>
```

**主要な操作・処理内容**：
1. データベース内の全インデックス情報の取得
2. 特定テーブルのインデックス詳細分析
3. 統計情報（ヒストグラム、サンプル行数）の取得
4. インデックス使用状況メトリクス（読み取り・更新回数）の確認
5. 断片化率の取得（オプション）
6. データ型情報を含むカラム定義の取得（オプション）

**画面遷移**：
- `Connect-DbaInstance`で接続を確立後に実行
- `Get-DbaDatabase`からパイプライン入力可能
- 取得結果は`Export-Csv`等で出力可能

**権限による表示制御**：
- データベースへの接続権限が必要
- sys.dm_db_index_usage_stats、sys.dm_db_partition_stats等のDMVへのアクセス権限が必要
- 断片化情報取得時はsys.dm_db_index_physical_statsへのアクセス権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 315 | Get-DbaHelpIndex | 主機能 | インデックス情報の取得 |

## 画面種別

CLI（コマンドラインインターフェース）- PowerShellコマンド

## URL/ルーティング

PowerShellコマンド: `Get-DbaHelpIndex`

## 入出力項目

### パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 条件付き | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | No | 対象データベース（ワイルドカード対応） |
| ExcludeDatabase | object[] | No | 除外するデータベース |
| ObjectName | string | No | 特定テーブル名（schema.table形式対応） |
| IncludeStats | switch | No | 統計オブジェクトも取得 |
| IncludeDataTypes | switch | No | カラムのデータ型情報を含める |
| IncludeFragmentation | switch | No | 断片化率を取得（実行時間増加） |
| InputObject | Database[] | No | パイプライン入力（Get-DbaDatabase出力） |
| Raw | switch | No | 数値を書式化せずに出力 |
| EnableException | switch | No | 例外を有効化 |

## 表示項目

### 出力オブジェクト（PSCustomObject）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Database | string | データベース名 |
| Object | string | テーブル名（schema.table形式） |
| Index | string | インデックス名（統計行は空） |
| Statistics | string | 統計名（インデックス行はnull） |
| IndexType | string | インデックスタイプ（Clustered, Nonclustered等）と修飾子 |
| KeyColumns | string | キー列のカンマ区切りリスト（DESCマーカー付き） |
| IncludeColumns | string | インクルード列のカンマ区切りリスト |
| FilterDefinition | string | フィルター式（フィルタードインデックスの場合） |
| FillFactor | string | フィルファクター値（0-100） |
| DataCompression | string | 圧縮タイプ（Row, Page, ColumnStore） |
| IndexReads | string/int | インデックス読み取り回数 |
| IndexUpdates | string/int | インデックス更新回数 |
| Size | string/dbasize | インデックスサイズ（KB） |
| IndexRows | string/int | インデックス行数 |
| IndexLookups | string/int | ルックアップ回数 |
| MostRecentlyUsed | DateTime | 最終使用日時 |
| StatsSampleRows | string/int | 統計サンプル行数 |
| StatsRowMods | string/int | 統計更新後の変更行数 |
| HistogramSteps | string/int | ヒストグラムステップ数 |
| StatsLastUpdated | DateTime | 統計最終更新日時 |
| IndexFragInPercent | string | 断片化率（-IncludeFragmentation時のみ） |

## イベント仕様

### 1-Get-DbaHelpIndex実行

1. パラメータの検証と前処理
2. テーブル条件の構築（ObjectName指定時）
3. 断片化情報取得の条件構築（IncludeFragmentation指定時）
4. SQL Serverバージョンに応じたクエリの選択（2005/2008以降）
5. データベースへの接続とクエリ実行
6. 結果の整形と出力（Raw指定に応じた書式化）

### 2-SQL Server 2008以降のクエリ処理

1. @IndexUsageStatsテーブル変数にDMVデータを格納
2. @StatsInfoテーブル変数に統計情報を格納
3. CTEを使用してインデックスサイズ、行数、使用状況を集計
4. インデックスと統計情報を結合して出力

### 3-SQL Server 2005のクエリ処理

1. @AllResultsテーブル変数に中間結果を格納
2. ObjectName指定時はDBCC SHOW_STATISTICSで統計詳細を取得
3. sys.sysindexesから変更行数を取得

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaHelpIndex | sys.indexes | SELECT | インデックス定義の取得 |
| Get-DbaHelpIndex | sys.dm_db_index_usage_stats | SELECT | 使用統計の取得 |
| Get-DbaHelpIndex | sys.dm_db_partition_stats | SELECT | パーティション統計の取得 |
| Get-DbaHelpIndex | sys.dm_db_index_physical_stats | SELECT | 断片化情報の取得（オプション） |
| Get-DbaHelpIndex | sys.stats | SELECT | 統計オブジェクト情報 |
| Get-DbaHelpIndex | sys.dm_db_stats_properties | SELECT | 統計プロパティの取得 |

本コマンドは読み取り専用操作のみを行い、データベースの変更は行いません。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|--------------|---------|
| MSG001 | エラー | Failure | 接続エラー |
| MSG002 | エラー | {db} is not accessible. Skipping. | データベースにアクセス不可 |
| MSG003 | エラー | Cannot process {db} on {server} | クエリ実行エラー |
| MSG004 | デバッグ | （クエリ内容） | Debug出力有効時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-FunctionでConnectionErrorカテゴリのエラーを報告 |
| データベースアクセス不可 | Stop-Functionでスキップして次のデータベースへ |
| クエリ実行エラー | Stop-Functionでエラーレコードと共に報告 |
| 最小バージョン未満 | Connect-DbaInstanceで-MinimumVersion 10を指定（SQL 2008以降） |

## 備考

- SQL Server 2005の場合、ObjectNameパラメータを指定しないと統計詳細が取得できない（パフォーマンス考慮）
- IncludeFragmentationを指定すると、sys.dm_db_index_physical_statsをDETAILEDモードで呼び出すため、大規模データベースでは実行時間が大幅に増加
- Rawスイッチを指定しない場合、数値は千単位の区切り文字付きで表示
- MostRecentlyUsedが1900年の場合はnullとして出力
- フィルタードインデックスの識別はSQL Server 2008以降のみ対応

---

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

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

### 推奨読解順序

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

本コマンドが問い合わせるDMVとシステムテーブルの関係を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaHelpIndex.ps1 | `public/Get-DbaHelpIndex.ps1` | 行225-591のSizesQueryでCTEの構造を確認 |

**読解のコツ**: CTEの連鎖（cteStatsInfo → cteIndexSizes → cteRows → cteIndex → cteResults → AllResults）を順に追うことで、データの集約方法を理解できます。

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

beginブロックでのクエリ構築とprocessブロックでの実行フローを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaHelpIndex.ps1 | `public/Get-DbaHelpIndex.ps1` | 行188-223のbeginブロックでパラメータ処理 |

**主要処理フロー**:
1. **191-195行**: TablePredicate変数の構築（ObjectName指定の有無で分岐）
2. **198-208行**: FragSelectColumn、FragJoinの構築（IncludeFragmentation指定時）
3. **211-215行**: IncludeStatsPredicate変数の構築
4. **218-222行**: IncludeDataTypesPredicate変数の構築

#### Step 3: クエリ実行と結果処理を理解する

processブロックでのデータベースクエリ実行と結果の整形処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaHelpIndex.ps1 | `public/Get-DbaHelpIndex.ps1` | 行1045-1140のprocessブロック |

**主要処理フロー**:
- **1049-1057行**: SqlInstanceの接続処理とデータベース取得
- **1063-1067行**: SQLバージョンに応じたクエリ選択
- **1075行**: db.Query()でクエリ実行
- **1077-1136行**: 結果のプロパティマッピングと出力オブジェクト生成

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

```
Get-DbaHelpIndex
    |
    +-- Connect-DbaInstance (MinimumVersion=10)
    |
    +-- Get-DbaDatabase (-Database, -ExcludeDatabase)
    |
    +-- foreach ($db in $InputObject)
            |
            +-- $db.Query($indexesQuery)
                    |
                    +-- SQL Server DMV/カタログビュー
                            +-- sys.indexes
                            +-- sys.index_columns
                            +-- sys.columns
                            +-- sys.tables
                            +-- sys.schemas
                            +-- sys.stats
                            +-- sys.stats_columns
                            +-- sys.partitions
                            +-- sys.dm_db_index_usage_stats
                            +-- sys.dm_db_partition_stats
                            +-- sys.dm_db_stats_properties
                            +-- sys.dm_db_index_physical_stats (オプション)
```

### データフロー図

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

SqlInstance/          +------------------+
Database          -->| Connect-Dba      |
SqlCredential        | Instance         |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | Get-DbaDatabase  |
                     +--------+---------+
                              |
                              v
                     +------------------+
ObjectName        -->| クエリ構築        |
IncludeStats         | (begin block)    |
IncludeDataTypes     +--------+---------+
IncludeFragmentation          |
                              v
                     +------------------+
                     | db.Query()       |---> PSCustomObject[]
                     | (process block)  |     (インデックス/統計情報)
                     +------------------+
                              |
                              v
                     +------------------+
Raw              -->| 結果整形          |---> 書式化された出力
                     | (プロパティ       |
                     |  マッピング)      |
                     +------------------+
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaHelpIndex.ps1 | `public/Get-DbaHelpIndex.ps1` | ソース | インデックス情報取得の主要ロジック |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 依存 | SQL Server接続処理 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | 依存 | データベースオブジェクト取得 |
