# 画面設計書 231-類似テーブル検索

## 概要

本ドキュメントは、dbatools PowerShell モジュールの `Find-DbaSimilarTable` コマンドに関する設計書です。このコマンドは、SQL Server データベース内のテーブルおよびビューの構造を比較し、類似した構造を持つオブジェクトを特定するためのユーティリティ機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：データベース運用において、アーカイブテーブルが本番テーブルの構造を正しく反映しているか、複数のデータベースで同様の目的を持つテーブルが存在しているかを特定することは重要です。本コマンドは、INFORMATION_SCHEMA ビューを使用してカラム名を比較し、テーブル間の構造的類似度を算出することで、テーブル設計の一貫性検証、データベース統合時の重複テーブル特定、アーカイブテーブルの検証などに活用できます。

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

**主要な操作・処理内容**：
1. 指定された SQL Server インスタンスに接続
2. 対象データベース内の全テーブル/ビューのカラム情報を取得
3. INFORMATION_SCHEMA.COLUMNS を使用してカラム名の一致率を算出
4. 一致率（MatchPercent）が閾値以上のテーブルペアを出力
5. 結果をパイプラインに即時出力

**画面遷移**：CLI コマンドのため画面遷移は存在しませんが、出力結果は他の dbatools コマンドにパイプライン接続可能です。

**権限による表示制御**：対象データベースへの SELECT 権限が必要です。IsAccessible プロパティでアクセス可能なデータベースのみ処理されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 669 | Find-DbaSimilarTable | 主機能 | 類似テーブルの検索 |
| 90 | Connect-DbaInstance | 補助機能 | SQL Server インスタンスへの接続 |
| 18 | Get-DbaDatabase | 補助機能 | データベース一覧の取得 |

## 画面種別

CLI コマンド（検索・一覧表示）

## URL/ルーティング

PowerShell コマンド: `Find-DbaSimilarTable`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象 SQL Server インスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | No | 検索対象データベース |
| ExcludeDatabase | object[] | No | 除外するデータベース |
| SchemaName | string | No | 対象スキーマ名 |
| TableName | string | No | 対象テーブル名 |
| ExcludeViews | switch | No | ビューを除外 |
| IncludeSystemDatabases | switch | No | システムデータベースを含める |
| MatchPercentThreshold | int | No | 一致率の閾値（0-100） |
| EnableException | switch | No | 例外を有効化 |

### 出力項目

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Server コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Table | string | 元テーブルの完全修飾名 |
| MatchingTable | string | 一致テーブルの完全修飾名 |
| MatchPercent | int | カラム名一致率（0-100） |
| OriginalDatabaseName | string | 元テーブルのデータベース名 |
| OriginalDatabaseId | int | 元テーブルのデータベースID |
| OriginalSchemaName | string | 元テーブルのスキーマ名 |
| OriginalTableName | string | 元テーブル名 |
| OriginalTableNameRankInDB | int | データベース内でのテーブルランク |
| OriginalTableType | string | テーブルタイプ（TABLE/VIEW） |
| OriginalColumnCount | int | 元テーブルのカラム数 |
| MatchingDatabaseName | string | 一致テーブルのデータベース名 |
| MatchingDatabaseId | int | 一致テーブルのデータベースID |
| MatchingSchemaName | string | 一致テーブルのスキーマ名 |
| MatchingTableName | string | 一致テーブル名 |
| MatchingTableType | string | 一致テーブルタイプ |
| MatchingColumnCount | int | 一致テーブルのカラム数 |

## 表示項目

パイプライン出力として PSCustomObject を返却します。デフォルト表示プロパティは設定されていません。

## イベント仕様

### 1-コマンド実行

1. SqlInstance パラメータで指定されたインスタンスに接続（最小バージョン: SQL Server 2005）
2. データベースフィルタリング（Database、ExcludeDatabase、IncludeSystemDatabases）
3. 各データベースに対して類似テーブル検索クエリを実行
4. 結果をパイプラインに即時出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 類似テーブル検索 | INFORMATION_SCHEMA.COLUMNS | SELECT | カラム情報の取得 |
| 類似テーブル検索 | INFORMATION_SCHEMA.TABLES | SELECT | テーブル情報の取得 |
| 類似テーブル検索 | sys.databases | SELECT | データベースID取得 |

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

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

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| Verbose | "Searching on database $db" | データベース検索開始時 |
| Verbose | "Found $vwCount tables/views in $db" | データベース検索完了時 |
| Verbose | "Found $totalCount total tables/views in $dbCount databases" | 全データベース検索完了時 |
| Error | "Failure" | 接続エラー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Function で警告を表示し、次のインスタンスへ続行 |
| SQL Server 2000 以前 | MinimumVersion 9 により接続拒否 |
| データベースアクセス不可 | IsAccessible チェックで除外 |

## 備考

- MatchPercent は元テーブルのカラム数を基準に算出（一致カラム数 / 元テーブルカラム数 * 100）
- 同名テーブルの比較は除外される（t.TABLE_NAME != c2.TABLE_NAME）
- 一致率 0 の結果は常に除外される
- SQL Server 2005 以降が必要（INFORMATION_SCHEMA の機能依存）

---

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

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

### 推奨読解順序

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

出力される PSCustomObject の構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaSimilarTable.ps1 | `public/Find-DbaSimilarTable.ps1` | 行283-303: 出力オブジェクトの構造定義 |

**読解のコツ**: PSCustomObject のプロパティ定義を確認し、SQL クエリの出力カラムとの対応を理解する。

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

処理の起点となるファイル・関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaSimilarTable.ps1 | `public/Find-DbaSimilarTable.ps1` | 関数全体の構造と処理フロー |

**主要処理フロー**:
1. **行138-246**: begin ブロック - SQL クエリの動的構築
2. **行249-256**: インスタンスへの接続
3. **行260-272**: データベースフィルタリング
4. **行277-304**: 各データベースでのクエリ実行と結果出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Find-DbaSimilarTable.ps1 | `public/Find-DbaSimilarTable.ps1` | 行141-207: メイン SQL クエリ構造 |

**主要処理フロー**:
- **行141-183**: SELECT 文とテーブル結合ロジック
- **行185-229**: WHERE 句の動的構築
- **行232-239**: HAVING 句で一致率閾値を適用

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

```
Find-DbaSimilarTable
    │
    ├─ Connect-DbaInstance (行253)
    │      └─ SQL Server SMO 接続
    │
    ├─ $server.Databases フィルタリング (行260-271)
    │
    └─ $db.Query($sql) (行280)
           └─ INFORMATION_SCHEMA クエリ実行
```

### データフロー図

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

SqlInstance ───────────▶ Connect-DbaInstance ───────────▶ Server Object
                               │
Database/ExcludeDatabase ─────▶ データベースフィルタリング ──▶ Database Collection
                               │
SchemaName/TableName ─────────▶ WHERE句動的構築 ───────────▶ SQL Query
                               │
MatchPercentThreshold ────────▶ HAVING句構築 ──────────────▶ SQL Query
                               │
                         $db.Query() 実行 ─────────────────▶ PSCustomObject[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaSimilarTable.ps1 | `public/Find-DbaSimilarTable.ps1` | ソース | メインコマンド実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続処理 |
