# 機能設計書 70-Get-DbaDbccStatistic

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Get-DbaDbccStatistic` コマンドレットの機能設計書です。DBCC SHOW_STATISTICSコマンドを使用して、テーブルやインデックス付きビューの統計情報を取得する機能について、その仕様と実装詳細を記述します。

### 本機能の処理概要

`Get-DbaDbccStatistic` は、SQL ServerのDBCC SHOW_STATISTICSコマンドを実行し、統計オブジェクトの詳細情報（ヒストグラム、密度ベクトル、ヘッダー情報、統計ストリーム）を取得するコマンドレットです。クエリオプティマイザが適切な実行プランを選択できているかを診断するのに役立ちます。

**業務上の目的・背景**：SQL Serverクエリオプティマイザは、統計情報に基づいて実行プランを決定します。統計が古くなったり偏ったりすると、オプティマイザは非効率なプランを選択し、パフォーマンスが低下します。本機能により、DBAは統計の最終更新日時、サンプリング率、値の分布パターンを分析し、UPDATE STATISTICSの必要性を判断できます。

**機能の利用シーン**：
- 古い統計の特定とUPDATE STATISTICS実行判断
- クエリパフォーマンス問題のトラブルシューティング
- 実行プラン選択の問題診断
- データ分布パターンの分析
- インスタンス全体の統計ヘルスチェック

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. 対象データベース・オブジェクト・統計の特定
3. DBCC SHOW_STATISTICSの実行（Option指定に応じた情報取得）
4. 結果を構造化オブジェクトとして出力

**関連システム・外部連携**：
- SQL Server インスタンス
- sys.stats, sys.objects（統計一覧取得用）

**権限による制御**：
- DBCC SHOW_STATISTICSの実行には対象テーブルへのSELECT権限が必要
- またはdb_owner, sysadmin権限

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI | 主画面 | PowerShellコマンドラインからの直接実行 |

## 機能種別

データベース診断（読み取り専用）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス | Mandatory, パイプライン入力可 |
| SqlCredential | PSCredential | No | 認証用資格情報 | - |
| Database | string[] | No | 対象データベース名 | - |
| Object | string | No | 対象テーブル/ビュー名（Schema.ObjectName形式） | - |
| Target | string | No | 対象統計/インデックス/カラム名 | - |
| Option | string | No | 取得情報タイプ（StatHeader/DensityVector/Histogram/StatsStream）。デフォルト: StatHeader | ValidateSet |
| NoInformationalMessages | switch | No | 情報メッセージを抑制 | - |
| EnableException | switch | No | 例外を有効にするフラグ | - |

### 入力データソース

- SQL Server インスタンスへの接続
- sys.stats, sys.objects（統計一覧取得用）

## 出力仕様

### 出力データ

#### 共通プロパティ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Server名 |
| Database | string | データベース名 |
| Object | string | オブジェクト名（Schema.Name） |
| Target | string | 統計/インデックス名 |
| Cmd | string | 実行されたDBCCコマンド |

#### Option=StatHeader時（デフォルト）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | 統計名 |
| Updated | datetime | 最終更新日時 |
| Rows | int | テーブルの総行数 |
| RowsSampled | int | サンプリングされた行数 |
| Steps | int | ヒストグラムのステップ数 |
| Density | float | 全体の密度値 |
| AverageKeyLength | float | キーの平均長（バイト） |
| StringIndex | string | 文字列インデックスかどうか |
| FilterExpression | string | フィルタ式（フィルタ統計の場合） |
| UnfilteredRows | int | フィルタ前の行数 |
| PersistedSamplePercent | float | 永続化されたサンプル率 |

#### Option=DensityVector時

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AllDensity | string | 密度値 |
| AverageLength | float | 平均長（バイト） |
| Columns | string | 対象カラム名 |

#### Option=Histogram時

| 項目名 | 型 | 説明 |
|--------|-----|------|
| RangeHiKey | object | ヒストグラムステップの上限値 |
| RangeRows | float | 範囲内の行数 |
| EqualRows | float | 上限値と等しい行数 |
| DistinctRangeRows | float | 範囲内の異なる値の数 |
| AverageRangeRows | float | 範囲内の平均行数 |

#### Option=StatsStream時

| 項目名 | 型 | 説明 |
|--------|-----|------|
| StatsStream | binary | 生の統計データ（バイナリ） |
| Rows | int | 行数 |
| DataPages | int | データページ数 |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. クエリテンプレート準備
   └─ DBCC SHOW_STATISTICS(#options#) WITH NO_INFOMSGS, {Option}
2. インスタンス接続
   └─ Connect-DbaInstanceでSQL Server接続
3. SQL Server 2000チェック
   └─ バージョン8の場合はObject/Target必須
4. データベースフィルタリング
   └─ Database指定時は対象DBを絞り込み
5. 統計一覧取得
   └─ Object/Target指定に応じてsys.statsをクエリ
6. 各統計に対してDBCC SHOW_STATISTICS実行
   └─ Option別に結果を解析
7. 結果出力
   └─ Option別のPSCustomObjectを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[クエリテンプレート準備]
    B --> C[インスタンスループ開始]
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function]
    E -->|Yes| G{SQL Server 2000?}
    G -->|Yes| H{Object/Target指定?}
    H -->|No| I[Warning: 必須]
    H -->|Yes| J[処理続行]
    G -->|No| J
    I --> K[次のインスタンス]
    J --> L[データベースループ開始]
    L --> M{IsAccessible?}
    M -->|No| N[スキップ]
    M -->|Yes| O{Object & Target指定?}
    O -->|両方| P[指定統計を使用]
    O -->|Objectのみ| Q[sys.statsでObject統計取得]
    O -->|なし| R[sys.statsで全統計取得]
    P --> S[統計ループ開始]
    Q --> S
    R --> S
    S --> T[DBCC SHOW_STATISTICS実行]
    T --> U{Option判定}
    U -->|StatHeader| V[StatHeader出力]
    U -->|DensityVector| W[DensityVector出力]
    U -->|Histogram| X[Histogram出力]
    U -->|StatsStream| Y[StatsStream出力]
    V --> Z{次の統計?}
    W --> Z
    X --> Z
    Y --> Z
    Z -->|Yes| S
    Z -->|No| AA{次のDB?}
    AA -->|Yes| L
    AA -->|No| AB{次のインスタンス?}
    AB -->|Yes| C
    AB -->|No| AC[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | OptionデフォルトはStatHeader | Option未指定時はStatHeaderを使用 | Option未指定時 |
| BR-02 | SQL 2000制限 | SQL Server 2000ではObject/Targetの両方が必須 | バージョン8 |
| BR-03 | アクセス不可DBスキップ | IsAccessibleがfalseのデータベースはスキップ | 常時 |
| BR-04 | 統計自動列挙 | Object/Target未指定時はsys.statsから全統計を取得 | Object/Target未指定時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DBCC SHOW_STATISTICS | なし | 読み取り | 統計情報の取得 |
| sys.stats, sys.objects | システムビュー | SELECT | 統計一覧取得 |

### テーブル別操作詳細

データベースへの書き込みは行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続失敗 | SQL Serverへの接続に失敗 | 接続情報を確認 |
| - | 権限不足 | SELECTまたはVIEW DATABASE STATE権限がない | 権限を付与 |
| - | DB非アクセス | データベースがアクセス不可 | DBの状態を確認 |
| - | オブジェクト未発見 | 指定Object/Targetが存在しない | 名前を確認 |

### リトライ仕様

リトライ処理なし

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

該当なし（読み取り専用操作）

## パフォーマンス要件

- 統計数に比例して処理時間が増加
- 大規模データベースでは全統計スキャンに時間がかかる可能性

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

- 対象テーブルへのSELECT権限が必要
- 読み取り専用操作のため、データへの影響なし

## 備考

- DBCC SHOW_STATISTICSはSQL Server 2005以降で利用可能
- SQL Server 2000ではObject/Targetの指定が必須

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbccStatistic.ps1 | `public/Get-DbaDbccStatistic.ps1` | 224-297行目: Option別の出力構造 |

**読解のコツ**: Optionによって出力プロパティが大きく異なることに注意。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbccStatistic.ps1 | `public/Get-DbaDbccStatistic.ps1` | 121-133行目: パラメータ定義 |

**主要処理フロー**:
1. **121-133行目**: パラメータ定義（Option ValidateSet含む）
2. **134-157行目**: begin ブロック - クエリ構築と統計クエリ定義
3. **158-304行目**: process ブロック - メイン処理

#### Step 3: 統計列挙ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbccStatistic.ps1 | `public/Get-DbaDbccStatistic.ps1` | sys.stats クエリ |

**主要処理フロー**:
- **147-156行目**: sys.stats, sys.objectsからの統計一覧クエリ
- **186-217行目**: Object/Target指定に応じた統計リスト構築

#### Step 4: 結果解析ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaDbccStatistic.ps1 | `public/Get-DbaDbccStatistic.ps1` | Option別の出力処理 |

**主要処理フロー**:
- **224-247行目**: StatHeader出力
- **248-263行目**: DensityVector出力
- **264-281行目**: Histogram出力
- **282-297行目**: StatsStream出力

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

```
Get-DbaDbccStatistic (public/Get-DbaDbccStatistic.ps1)
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続
    │
    ├─ db.Query() (統計一覧取得)
    │      └─ sys.stats, sys.objects JOIN
    │
    └─ Invoke-DbaQuery (各統計)
           └─ DBCC SHOW_STATISTICS('Object', 'Target') WITH {Option}
```

### データフロー図

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

SqlInstance ──────▶ Connect-DbaInstance ──┐
                                          │
Database ─────────▶ フィルタリング ────────┤
                                          │
Object ───────────▶                       │
Target ───────────▶ sys.statsクエリ ──────┤
                                          │
Option ───────────▶ SHOW_STATISTICSオプション設定
                                          │
                                          ▼
                                   DBCC SHOW_STATISTICS
                                          │
                   ┌──────────────────────┼──────────────────────┐
                   │                      │                      │
                   ▼                      ▼                      ▼
              StatHeader            DensityVector           Histogram
                   │                      │                      │
                   └──────────────────────┼──────────────────────┘
                                          │
                                          ▼
                                   PSCustomObject
                              (Option別のプロパティ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbccStatistic.ps1 | `public/Get-DbaDbccStatistic.ps1` | ソース | メイン実装ファイル |
| Get-DbaDbccStatistic.Tests.ps1 | `tests/Get-DbaDbccStatistic.Tests.ps1` | テスト | 単体テスト |
