# 画面設計書 36-Query Store

## 概要

本ドキュメントは、dbatoolsにおけるQuery Store管理機能の設計仕様を定義する。

### 本画面の処理概要

Query Store管理機能は、SQL ServerのQuery Store設定の取得・変更を行うPowerShellコマンド群を提供する。Query Storeはクエリの実行計画とランタイム統計を自動的に記録し、パフォーマンス分析とプランリグレッションのトラブルシューティングを支援する機能である。

**業務上の目的・背景**：Query StoreはSQL Server 2016以降で導入されたパフォーマンス監視機能である。クエリの実行計画の変更を追跡し、パフォーマンス低下の原因を特定するために使用される。本機能は、複数データベース・インスタンスにわたるQuery Store設定の一元管理と、一貫した設定ポリシーの適用を支援する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする。
- `Get-DbaDbQueryStoreOption` - Query Store設定の取得
- `Set-DbaDbQueryStoreOption` - Query Store設定の変更

**主要な操作・処理内容**：
1. Query Store設定の取得：状態、収集間隔、ストレージサイズ、キャプチャモードなどの取得
2. Query Store設定の変更：状態の有効化/無効化、各種パラメータの設定

**画面遷移**：本機能はCLIベースのため画面遷移は存在しないが、以下のコマンド間で連携が可能。
- `Get-DbaDatabase` から `Set-DbaDbQueryStoreOption` へパイプライン入力
- パフォーマンス監視ワークフローでの設定確認と調整

**権限による表示制御**：Query Store設定の変更にはデータベースのALTER権限が必要。設定の参照にはVIEW DATABASE STATE権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 270 | Get-DbaDbQueryStoreOption | 主機能 | Query Store設定の取得 |
| 271 | Set-DbaDbQueryStoreOption | 主機能 | Query Store設定の変更 |

## 画面種別

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

## URL/ルーティング

N/A（PowerShellモジュールのコマンドとして提供）

## 入出力項目

### Get-DbaDbQueryStoreOption

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 必須 | 対象SQLインスタンス |
| SqlCredential | PSCredential | - | 代替認証情報 |
| Database | object[] | - | 対象データベース名フィルター |
| ExcludeDatabase | object[] | - | 除外データベース名 |
| EnableException | switch | - | 例外処理の有効化 |

### Set-DbaDbQueryStoreOption

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | 必須 | 対象SQLインスタンス |
| SqlCredential | PSCredential | - | 代替認証情報 |
| Database | object[] | - | 対象データベース名 |
| ExcludeDatabase | object[] | - | 除外データベース名 |
| AllDatabases | switch | - | 全ユーザーデータベースを対象 |
| State | string | - | 状態（ReadWrite/ReadOnly/Off） |
| FlushInterval | int64 | - | データフラッシュ間隔（秒） |
| CollectionInterval | int64 | - | 統計収集間隔（分） |
| MaxSize | int64 | - | 最大ストレージサイズ（MB） |
| CaptureMode | string | - | キャプチャモード（Auto/All/None/Custom） |
| CleanupMode | string | - | クリーンアップモード（Auto/Off） |
| StaleQueryThreshold | int64 | - | 古いクエリのしきい値（日） |
| MaxPlansPerQuery | int64 | - | クエリあたりの最大プラン数（SQL 2017+） |
| WaitStatsCaptureMode | string | - | 待機統計キャプチャモード（On/Off）（SQL 2017+） |
| CustomCapturePolicyExecutionCount | int64 | - | カスタムキャプチャの実行回数しきい値（SQL 2019+） |
| CustomCapturePolicyTotalCompileCPUTimeMS | int64 | - | カスタムキャプチャのコンパイルCPU時間（ms）（SQL 2019+） |
| CustomCapturePolicyTotalExecutionCPUTimeMS | int64 | - | カスタムキャプチャの実行CPU時間（ms）（SQL 2019+） |
| CustomCapturePolicyStaleThresholdHours | int64 | - | カスタムキャプチャの古いしきい値（時間）（SQL 2019+） |
| EnableException | switch | - | 例外処理の有効化 |

## 表示項目

### Get-DbaDbQueryStoreOption / Set-DbaDbQueryStoreOption 出力（SQL 2016）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| Database | string | データベース名 |
| ActualState | string | 現在の状態（ReadWrite/ReadOnly/Off） |
| DataFlushIntervalInSeconds | int | データフラッシュ間隔（秒） |
| StatisticsCollectionIntervalInMinutes | int | 統計収集間隔（分） |
| MaxStorageSizeInMB | int | 最大ストレージサイズ（MB） |
| CurrentStorageSizeInMB | int | 現在のストレージサイズ（MB） |
| QueryCaptureMode | string | キャプチャモード（All/Auto/None/Custom） |
| SizeBasedCleanupMode | string | クリーンアップモード（Auto/Off） |
| StaleQueryThresholdInDays | int | 古いクエリのしきい値（日） |

### 追加出力項目（SQL 2017以降）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| MaxPlansPerQuery | int | クエリあたりの最大プラン数 |
| WaitStatsCaptureMode | string | 待機統計キャプチャモード（On/Off） |

### 追加出力項目（SQL 2019以降）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CustomCapturePolicyExecutionCount | int | カスタムキャプチャの実行回数しきい値 |
| CustomCapturePolicyTotalCompileCPUTimeMS | int | カスタムキャプチャのコンパイルCPU時間（ms） |
| CustomCapturePolicyTotalExecutionCPUTimeMS | int | カスタムキャプチャの実行CPU時間（ms） |
| CustomCapturePolicyStaleThresholdHours | int | カスタムキャプチャの古いしきい値（時間） |

## イベント仕様

### 1-Query Store設定取得

Get-DbaDbQueryStoreOptionコマンド実行時：
1. SQL Server 2016以降（バージョン13以上）への接続を確認
2. システムデータベース（master、tempdb、model）を除外
3. アクセス可能なユーザーデータベースのQueryStoreOptionsプロパティを取得
4. バージョン14（SQL 2017）の場合：sys.database_query_store_optionsからMaxPlansPerQuery、WaitStatsCaptureMode追加取得
5. バージョン15以降（SQL 2019+）の場合：カスタムキャプチャポリシー設定も追加取得
6. カスタムプロパティ（ComputerName、InstanceName等）を追加して出力

### 2-Query Store設定変更

Set-DbaDbQueryStoreOptionコマンド実行時：
1. Database、ExcludeDatabase、AllDatabasesのいずれかの指定を確認
2. 変更対象パラメータの指定を確認
3. SQL Server 2016以降への接続を確認
4. CustomキャプチャモードはSQL 2019以降のみ許可
5. カスタムキャプチャポリシーパラメータはSQL 2019以降のみ適用
6. 各設定をSMOプロパティまたはALTER DATABASE文で変更
7. State変更時は即座にAlter()を実行
8. 他の設定は最後にまとめてAlter()を実行
9. 変更後にGet-DbaDbQueryStoreOptionで結果を返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Query Store設定取得 | sys.database_query_store_options | SELECT | Query Store設定の参照 |
| Query Store設定変更 | sys.database_query_store_options | UPDATE | Query Store設定の変更 |

### ALTER DATABASE文詳細

#### 基本設定（SMO経由）
```
DesiredState = ReadWrite/ReadOnly/Off
DataFlushIntervalInSeconds = {value}
StatisticsCollectionIntervalInMinutes = {value}
MaxStorageSizeInMB = {value}
QueryCaptureMode = Auto/All/None/Custom
SizeBasedCleanupMode = Auto/Off
StaleQueryThresholdInDays = {value}
```

#### SQL 2017以降（T-SQL経由）
```sql
ALTER DATABASE [DatabaseName] SET QUERY_STORE = ON (MAX_PLANS_PER_QUERY = {value})
ALTER DATABASE [DatabaseName] SET QUERY_STORE = ON (WAIT_STATS_CAPTURE_MODE = ON/OFF)
```

#### SQL 2019以降（T-SQL経由、Customモード時）
```sql
ALTER DATABASE [DatabaseName] SET QUERY_STORE = ON (QUERY_CAPTURE_POLICY = (STALE_CAPTURE_POLICY_THRESHOLD = {value} HOURS))
ALTER DATABASE [DatabaseName] SET QUERY_STORE = ON (QUERY_CAPTURE_POLICY = (EXECUTION_COUNT = {value}))
ALTER DATABASE [DatabaseName] SET QUERY_STORE = ON (QUERY_CAPTURE_POLICY = (TOTAL_COMPILE_CPU_TIME_MS = {value}))
ALTER DATABASE [DatabaseName] SET QUERY_STORE = ON (QUERY_CAPTURE_POLICY = (TOTAL_EXECUTION_CPU_TIME_MS = {value}))
```

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| MSG001 | エラー | You must specify a database(s) to execute against using either -Database, -ExcludeDatabase or -AllDatabases | データベース指定なし |
| MSG002 | エラー | You must specify something to change. | 変更パラメータなし |
| MSG003 | エラー | Custom capture mode can only be set in SQL Server 2019 and above | SQL 2019未満でCustomモード指定 |
| MSG004 | 警告 | Custom Capture Policies can only be set in SQL Server 2019 and above. These options will be skipped for {instance} | SQL 2019未満でカスタムポリシー指定 |
| MSG005 | 警告 | State is set to Off; cannot change values. Please update State to ReadOnly or ReadWrite. | StateがOffで他設定変更試行 |
| MSG006 | 警告 | The database {db} on server {instance} is not accessible. Skipping database. | アクセス不可なデータベース |
| MSG007 | 確認 | Changing DesiredState to {state} | 状態変更確認 |
| MSG008 | 確認 | Changing DataFlushIntervalInSeconds to {value} | フラッシュ間隔変更確認 |
| MSG009 | 確認 | Changing StatisticsCollectionIntervalInMinutes to {value} | 収集間隔変更確認 |
| MSG010 | 確認 | Changing MaxStorageSizeInMB to {value} | 最大サイズ変更確認 |
| MSG011 | 確認 | Changing QueryCaptureMode to {value} | キャプチャモード変更確認 |
| MSG012 | 確認 | Changing SizeBasedCleanupMode to {value} | クリーンアップモード変更確認 |
| MSG013 | 確認 | Changing StaleQueryThresholdInDays to {value} | しきい値変更確認 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server 2016未満 | Stop-Functionでエラー出力して続行 |
| データベース指定なし | Stop-Functionでエラー出力して終了 |
| 変更パラメータなし | Stop-Functionでエラー出力して終了 |
| SQL 2019未満でCustomモード | Stop-Functionでエラー出力して続行 |
| SQL 2019未満でカスタムポリシー | 警告出力してスキップ |
| StateがOffで他設定変更 | 警告出力してスキップ |
| アクセス不可なデータベース | 警告出力してスキップ |
| 設定変更失敗 | Stop-Functionでエラー出力して続行 |

## 備考

- Query StoreはSQL Server 2016以降でサポート
- システムデータベース（master、tempdb、model）はQuery Store対象外
- SQL 2016（v13）：基本設定のみ
- SQL 2017（v14）：MaxPlansPerQuery、WaitStatsCaptureMode追加
- SQL 2019（v15+）：Customキャプチャモードとカスタムキャプチャポリシー追加
- StateがOffの場合、他の設定変更は不可（先にStateをReadWriteまたはReadOnlyに変更が必要）
- Query Storeのデータはデータベース内に保存され、バックアップに含まれる

---

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

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

### 推奨読解順序

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

Query Store管理で扱う主要なデータ構造はSMOのQueryStoreOptionsオブジェクトである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbQueryStoreOption.ps1 | `public/Get-DbaDbQueryStoreOption.ps1` | 出力オブジェクトの構造（行9-38）を確認 |

**読解のコツ**: QueryStoreOptionsオブジェクトはバージョンによってプロパティが異なる。v13（SQL 2016）、v14（SQL 2017）、v15+（SQL 2019+）の違いに注意。

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

各コマンドのprocess{}ブロックが処理の起点となる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbQueryStoreOption.ps1 | `public/Get-DbaDbQueryStoreOption.ps1` | 行104-144のprocessブロック |
| 2-2 | Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | 行195-347のprocessブロック |

**主要処理フロー（Get-DbaDbQueryStoreOption）**:
1. **行107**: Connect-DbaInstanceでバージョン13以上への接続
2. **行113**: システムDBを除外してデータベース取得
3. **行117**: QueryStoreOptionsプロパティを取得
4. **行119-142**: バージョンに応じた追加プロパティの取得と出力

#### Step 3: Query Store設定変更処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | パラメータ検証（行196-204） |
| 3-2 | Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | 状態変更処理（行233-239） |
| 3-3 | Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | 各パラメータ変更（行246-280） |
| 3-4 | Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | SQL 2017+追加設定（行284-298） |
| 3-5 | Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | SQL 2019+カスタムポリシー（行300-325） |

**主要処理フロー（Set-DbaDbQueryStoreOption）**:
- **行233-239**: State変更は即座にAlter()実行
- **行241-244**: StateがOffの場合は他設定変更をスキップ
- **行246-280**: 基本設定のSMOプロパティ変更
- **行284-298**: v14+のALTER DATABASE文生成
- **行300-325**: v15+のカスタムキャプチャポリシー設定
- **行328-340**: 最終的なAlter()実行とALTER DATABASE文実行

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

```
Get-DbaDbQueryStoreOption
    |
    +-- Connect-DbaInstance (MinimumVersion 13)
    |
    +-- Get-DbaDatabase
    |
    +-- Database.QueryStoreOptions (SMO)
    |
    +-- Invoke-DbaQuery (v14+追加プロパティ取得)
    |       Query: sys.database_query_store_options
    |
    +-- Select-DefaultView (出力整形)

Set-DbaDbQueryStoreOption
    |
    +-- Connect-DbaInstance (MinimumVersion 13)
    |
    +-- Get-DbaDatabase
    |
    +-- QueryStoreOptions.DesiredState = {State}
    |
    +-- QueryStoreOptions.{Property} = {Value}
    |
    +-- QueryStoreOptions.Alter()
    |
    +-- Database.Alter()
    |
    +-- Database.Query() (v14+/v15+ ALTER DATABASE)
    |
    +-- Get-DbaDbQueryStoreOption (結果取得)
```

### データフロー図

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

SqlInstance    ----->  Connect-DbaInstance
                            |
Database       ----->  フィルタリング           ----->  対象データベース
                            |
ExcludeDatabase -----> システムDB除外
                            |
AllDatabases   ----->  全ユーザーDB取得
                            |
                     QueryStoreOptions取得
                            |
                     バージョン判定
                            |
State          ----->  DesiredState変更        ----->  SMO Alter
FlushInterval  ----->  DataFlushInterval変更
MaxSize        ----->  MaxStorageSizeInMB変更
CaptureMode    ----->  QueryCaptureMode変更
...                    ...
                            |
                     Get-DbaDbQueryStoreOption  ----->  QueryStoreOptions
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbQueryStoreOption.ps1 | `public/Get-DbaDbQueryStoreOption.ps1` | ソース | Query Store設定取得コマンド |
| Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | ソース | Query Store設定変更コマンド |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得（依存コマンド） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続（依存コマンド） |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | クエリ実行（依存コマンド） |
